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