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