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