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