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_create_from_udev()
 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_create_from_udev()
 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_create_from_udev(const struct libinput_interface *interface,
 706                           void *user_data,
 707                           struct udev *udev,
 708                           const char *seat_id);
 709 /**
 710  * @ingroup base
 711  *
 712  * Create a new libinput context from the given path. This context
 713  * represents one single device only, it will not respond to new devices
 714  * being added and reading from the device after it was removed will fail.
 715  *
 716  * @param interface The callback interface
 717  * @param user_data Caller-specific data passed to the various callback
 718  * interfaces.
 719  * @param path Path to an input device
 720  *
 721  * @return An initialized libinput context, ready to handle events or NULL on
 722  * error.
 723  */
 724 struct libinput *
 725 libinput_create_from_path(const struct libinput_interface *interface,
 726                           void *user_data,
 727                           const char *path);
 728
 729 /**
 730  * @ingroup base
 731  *
 732  * Add a device to a libinput context initialized with
 733  * libinput_path_create_from_device(). If successful, the device will be
 734  * added to the internal list and re-opened on libinput_resume(). The device
 735  * can be removed with libinput_path_remove_device().
 736  *
 737  * If the device was successfully initialized, it is returned in the device
 738  * argument. The lifetime of the returned device pointer is limited until
 739  * the next linput_dispatch(), use libinput_device_ref() to keep a permanent
 740  * reference.
 741  *
 742  * @param libinput A previously initialized libinput context
 743  * @param path Path to an input device
 744  * @return The newly initiated device on success, or NULL on failure.
 745  *
 746  * @note It is an application bug to call this function on a libinput
 747  * context initialize with libinput_udev_create_for_seat().
 748  */
 749 struct libinput_device *
 750 libinput_path_add_device(struct libinput *libinput,
 751                          const char *path);
 752
 753 /**
 754  * @ingroup base
 755  *
 756  * Remove a device from a libinput context initialized with
 757  * libinput_path_create_from_device() or added to such a context with
 758  * libinput_path_add_device().
 759  *
 760  * Events already processed from this input device are kept in the queue,
 761  * the LIBINPUT_EVENT_DEVICE_REMOVED event marks the end of events for this
 762  * device.
 763  *
 764  * If no matching device exists, this function does nothing.
 765  *
 766  * @param device A libinput device
 767  *
 768  * @note It is an application bug to call this function on a libinput
 769  * context initialize with libinput_udev_create_for_seat().
 770  */
 771 void
 772 libinput_path_remove_device(struct libinput_device *device);
 773
 774 /**
 775  * @ingroup base
 776  *
 777  * libinput keeps a single file descriptor for all events. Call into
 778  * libinput_dispatch() if any events become available on this fd.
 779  *
 780  * @return the file descriptor used to notify of pending events.
 781  */
 782 int
 783 libinput_get_fd(struct libinput *libinput);
 784
 785 /**
 786  * @ingroup base
 787  *
 788  * Main event dispatchment function. Reads events of the file descriptors
 789  * and processes them internally. Use libinput_get_event() to retrieve the
 790  * events.
 791  *
 792  * Dispatching does not necessarily queue libinput events.
 793  *
 794  * @param libinput A previously initialized libinput context
 795  *
 796  * @return 0 on success, or a negative errno on failure
 797  */
 798 int
 799 libinput_dispatch(struct libinput *libinput);
 800
 801 /**
 802  * @ingroup base
 803  *
 804  * Retrieve the next event from libinput's internal event queue.
 805  *
 806  * After handling the retrieved event, the caller must destroy it using
 807  * libinput_event_destroy().
 808  *
 809  * @param libinput A previously initialized libinput context
 810  * @return The next available event, or NULL if no event is available.
 811  */
 812 struct libinput_event *
 813 libinput_get_event(struct libinput *libinput);
 814
 815 /**
 816  * @ingroup base
 817  *
 818  * Return the type of the next event in the internal queue. This function
 819  * does not pop the event off the queue and the next call to
 820  * libinput_get_event() returns that event.
 821  *
 822  * @param libinput A previously initialized libinput context
 823  * @return The event type of the next available event or LIBINPUT_EVENT_NONE
 824  * if no event is availble.
 825  */
 826 enum libinput_event_type
 827 libinput_next_event_type(struct libinput *libinput);
 828
 829 /**
 830  * @ingroup base
 831  *
 832  * @param libinput A previously initialized libinput context
 833  * @return the caller-specific data previously assigned in
 834  * libinput_create_udev().
 835  */
 836 void *
 837 libinput_get_user_data(struct libinput *libinput);
 838
 839 /**
 840  * @ingroup base
 841  *
 842  * Resume a suspended libinput context. This re-enables device
 843  * monitoring and adds existing devices.
 844  *
 845  * @param libinput A previously initialized libinput context
 846  * @see libinput_suspend
 847  *
 848  * @return 0 on success or -1 on failure
 849  */
 850 int
 851 libinput_resume(struct libinput *libinput);
 852
 853 /**
 854  * @ingroup base
 855  *
 856  * Suspend monitoring for new devices and close existing devices.
 857  * This all but terminates libinput but does keep the context
 858  * valid to be resumed with libinput_resume().
 859  *
 860  * @param libinput A previously initialized libinput context
 861  */
 862 void
 863 libinput_suspend(struct libinput *libinput);
 864
 865 /**
 866  * @ingroup base
 867  *
 868  * Destroy the libinput context. After this, object references associated with
 869  * the destroyed context are invalid and may not be interacted with.
 870  *
 871  * @param libinput A previously initialized libinput context
 872  */
 873 void
 874 libinput_destroy(struct libinput *libinput);
 875
 876 /**
 877  * @defgroup seat Initialization and manipulation of seats
 878  *
 879  * A seat has two identifiers, the physical name and the logical name. The
 880  * physical name is summarized as the list of devices a process on the same
 881  * physical seat has access to.
 882  *
 883  * The logical seat name is the seat name for a logical group of devices. A
 884  * compositor may use that to create additonal seats as independent device
 885  * sets. Alternatively, a compositor may limit itself to a single logical
 886  * seat, leaving a second compositor to manage devices on the other logical
 887  * seats.
 888  *
 889  * @code
 890  * +---+--------+------------+------------------------+------------+
 891  * |   | event0 |            |                        | log seat A |
 892  * | K +--------+            |                        +------------+
 893  * | e | event1 | phys seat0 |    libinput context 1  |            |
 894  * | r +--------+            |                        | log seat B |
 895  * | n | event2 |            |                        |            |
 896  * | e +--------+------------+------------------------+------------+
 897  * | l | event3 | phys seat1 |    libinput context 2  | log seat C |
 898  * +---+--------+------------+------------------------+------------+
 899  * @endcode
 900  */
 901
 902 /**
 903  * @ingroup seat
 904  *
 905  * Increase the refcount of the seat. A seat will be freed whenever the
 906  * refcount reaches 0. This may happen during dispatch if the
 907  * seat was removed from the system. A caller must ensure to reference
 908  * the seat correctly to avoid dangling pointers.
 909  *
 910  * @param seat A previously obtained seat
 911  */
 912 void
 913 libinput_seat_ref(struct libinput_seat *seat);
 914
 915 /**
 916  * @ingroup seat
 917  *
 918  * Decrease the refcount of the seat. A seat will be freed whenever the
 919  * refcount reaches 0. This may happen during dispatch if the
 920  * seat was removed from the system. A caller must ensure to reference
 921  * the seat correctly to avoid dangling pointers.
 922  *
 923  * @param seat A previously obtained seat
 924  */
 925 void
 926 libinput_seat_unref(struct libinput_seat *seat);
 927
 928 /**
 929  * @ingroup seat
 930  *
 931  * Set caller-specific data associated with this seat. libinput does
 932  * not manage, look at, or modify this data. The caller must ensure the
 933  * data is valid.
 934  *
 935  * @param seat A previously obtained seat
 936  * @param user_data Caller-specific data pointer
 937  * @see libinput_seat_get_user_data
 938  */
 939 void
 940 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
 941
 942 /**
 943  * @ingroup seat
 944  *
 945  * Get the caller-specific data associated with this seat, if any.
 946  *
 947  * @param seat A previously obtained seat
 948  * @return Caller-specific data pointer or NULL if none was set
 949  * @see libinput_seat_set_user_data
 950  */
 951 void *
 952 libinput_seat_get_user_data(struct libinput_seat *seat);
 953
 954 /**
 955  * @ingroup seat
 956  *
 957  * Return the physical name of the seat. For libinput contexts created from
 958  * udev, this is always the same value as passed into
 959  * libinput_create_from_udev() and all seats from that context will have the
 960  * same physical name.
 961  *
 962  * The physical name of the seat is one that is usually set by the system or
 963  * lower levels of the stack. In most cases, this is the base filter for
 964  * devices - devices assigned to seats outside the current seat will not
 965  * be available to the caller.
 966  *
 967  * @param seat A previously obtained seat
 968  * @return the physical name of this seat
 969  */
 970 const char *
 971 libinput_seat_get_physical_name(struct libinput_seat *seat);
 972
 973 /**
 974  * @ingroup seat
 975  *
 976  * Return the logical name of the seat. This is an identifier to group sets
 977  * of devices within the compositor.
 978  *
 979  * @param seat A previously obtained seat
 980  * @return the logical name of this seat
 981  */
 982 const char *
 983 libinput_seat_get_logical_name(struct libinput_seat *seat);
 984
 985 /**
 986  * @defgroup device Initialization and manipulation of input devices
 987  */
 988
 989 /**
 990  * @ingroup device
 991  *
 992  * Increase the refcount of the input device. An input device will be freed
 993  * whenever the refcount reaches 0. This may happen during dispatch if the
 994  * device was removed from the system. A caller must ensure to reference
 995  * the device correctly to avoid dangling pointers.
 996  *
 997  * @param device A previously obtained device
 998  */
 999 void
1000 libinput_device_ref(struct libinput_device *device);
1001
1002 /**
1003  * @ingroup device
1004  *
1005  * Decrease the refcount of the input device. An input device will be freed
1006  * whenever the refcount reaches 0. This may happen during dispatch if the
1007  * device was removed from the system. A caller must ensure to reference
1008  * the device correctly to avoid dangling pointers.
1009  *
1010  * @param device A previously obtained device
1011  */
1012 void
1013 libinput_device_unref(struct libinput_device *device);
1014
1015 /**
1016  * @ingroup device
1017  *
1018  * Set caller-specific data associated with this input device. libinput does
1019  * not manage, look at, or modify this data. The caller must ensure the
1020  * data is valid.
1021  *
1022  * @param device A previously obtained device
1023  * @param user_data Caller-specific data pointer
1024  * @see libinput_device_get_user_data
1025  */
1026 void
1027 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
1028
1029 /**
1030  * @ingroup device
1031  *
1032  * Get the caller-specific data associated with this input device, if any.
1033  *
1034  * @param device A previously obtained device
1035  * @return Caller-specific data pointer or NULL if none was set
1036  * @see libinput_device_set_user_data
1037  */
1038 void *
1039 libinput_device_get_user_data(struct libinput_device *device);
1040
1041 /**
1042  * @ingroup device
1043  *
1044  * Get the system name of the device.
1045  *
1046  * @param device A previously obtained device
1047  * @return System name of the device
1048  */
1049 const char *
1050 libinput_device_get_sysname(struct libinput_device *device);
1051
1052 /**
1053  * @ingroup device
1054  *
1055  * A device may be mapped to a single output, or all available outputs. If a
1056  * device is mapped to a single output only, a relative device may not move
1057  * beyond the boundaries of this output. An absolute device has its input
1058  * coordinates mapped to the extents of this output.
1059  *
1060  * @return the name of the output this device is mapped to, or NULL if no
1061  * output is set
1062  */
1063 const char *
1064 libinput_device_get_output_name(struct libinput_device *device);
1065
1066 /**
1067  * @ingroup device
1068  *
1069  * Get the seat associated with this input device.
1070  *
1071  * @param device A previously obtained device
1072  * @return The seat this input device belongs to
1073  */
1074 struct libinput_seat *
1075 libinput_device_get_seat(struct libinput_device *device);
1076
1077 /**
1078  * @ingroup device
1079  *
1080  * Update the LEDs on the device, if any. If the device does not have
1081  * LEDs, or does not have one or more of the LEDs given in the mask, this
1082  * function does nothing.
1083  *
1084  * @param device A previously obtained device
1085  * @param leds A mask of the LEDs to set, or unset.
1086  */
1087 void
1088 libinput_device_led_update(struct libinput_device *device,
1089                            enum libinput_led leds);
1090
1091 /**
1092  * @ingroup device
1093  *
1094  * Set the bitmask in keys to the bitmask of the keys present on the device
1095  * (see linux/input.h), up to size characters.
1096  *
1097  * @param device A current input device
1098  * @param keys An array filled with the bitmask for the keys
1099  * @param size Size of the keys array
1100  */
1101 int
1102 libinput_device_get_keys(struct libinput_device *device,
1103                          char *keys, size_t size);
1104
1105 /**
1106  * @ingroup device
1107  *
1108  * Apply the 3x3 transformation matrix to absolute device coordinates. This
1109  * matrix has no effect on relative events.
1110  *
1111  * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
1112  * @code
1113  * [ a  b  c ]   [ x ]
1114  * [ d  e  f ] * [ y ]
1115  * [ 0  0  1 ]   [ 1 ]
1116  * @endcode
1117  */
1118 void
1119 libinput_device_calibrate(struct libinput_device *device,
1120                           float calibration[6]);
1121
1122 /**
1123  * @ingroup device
1124  *
1125  * Check if the given device has the specified capability
1126  *
1127  * @return 1 if the given device has the capability or 0 if not
1128  */
1129 int
1130 libinput_device_has_capability(struct libinput_device *device,
1131                                enum libinput_device_capability capability);
1132
1133 #endif /* LIBINPUT_H */