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  * libinput 24.8 fixed point real number.
  39  */
  40 typedef int32_t li_fixed_t;
  41
  42 /**
  43  * @ingroup device
  44  *
  45  * Capabilities on a device. A device may have one or more capabilities
  46  * at a time, and capabilities may appear or disappear during the
  47  * lifteime of the device.
  48  */
  49 enum libinput_device_capability {
  50         LIBINPUT_DEVICE_CAP_KEYBOARD = 0,
  51         LIBINPUT_DEVICE_CAP_POINTER = 1,
  52         LIBINPUT_DEVICE_CAP_TOUCH = 2,
  53 };
  54
  55 /**
  56  * @ingroup device
  57  *
  58  * Logical state of a key. Note that the logical state may not represent
  59  * the physical state of the key.
  60  */
  61 enum libinput_keyboard_key_state {
  62         LIBINPUT_KEYBOARD_KEY_STATE_RELEASED = 0,
  63         LIBINPUT_KEYBOARD_KEY_STATE_PRESSED = 1,
  64 };
  65
  66 /**
  67  * @ingroup device
  68  *
  69  * Mask reflecting LEDs on a device.
  70  */
  71 enum libinput_led {
  72         LIBINPUT_LED_NUM_LOCK = (1 << 0),
  73         LIBINPUT_LED_CAPS_LOCK = (1 << 1),
  74         LIBINPUT_LED_SCROLL_LOCK = (1 << 2),
  75 };
  76
  77 /**
  78  * @ingroup device
  79  *
  80  * Logical state of a physical button. Note that the logical state may not
  81  * represent the physical state of the button.
  82  */
  83 enum libinput_pointer_button_state {
  84         LIBINPUT_POINTER_BUTTON_STATE_RELEASED = 0,
  85         LIBINPUT_POINTER_BUTTON_STATE_PRESSED = 1,
  86 };
  87
  88
  89 /**
  90  * @ingroup device
  91  *
  92  * Axes on a device that are not x or y coordinates.
  93  */
  94 enum libinput_pointer_axis {
  95         LIBINPUT_POINTER_AXIS_VERTICAL_SCROLL = 0,
  96         LIBINPUT_POINTER_AXIS_HORIZONTAL_SCROLL = 1,
  97 };
  98
  99 /**
 100  * @ingroup device
 101  *
 102  * Logical touch state of a touch point. A touch point usually follows the
 103  * sequence down, motion, up, with the number of motion events being zero or
 104  * greater. If a touch point was used for gesture interpretation internally
 105  * and will not generate any further events, the touchpoint is cancelled.
 106  *
 107  * A frame event is set after a set of touchpoints that constitute one
 108  * logical set of points at a sampling point.
 109  */
 110 enum libinput_touch_type {
 111         LIBINPUT_TOUCH_TYPE_DOWN = 0,
 112         LIBINPUT_TOUCH_TYPE_UP = 1,
 113         LIBINPUT_TOUCH_TYPE_MOTION = 2,
 114         LIBINPUT_TOUCH_TYPE_FRAME = 3,
 115         LIBINPUT_TOUCH_TYPE_CANCEL = 4,
 116 };
 117
 118 /**
 119  * @ingroup base
 120  *
 121  * Event type for events returned by libinput_get_event().
 122  */
 123 enum libinput_event_type {
 124         LIBINPUT_EVENT_ADDED_SEAT = 0,
 125         LIBINPUT_EVENT_REMOVED_SEAT,
 126         LIBINPUT_EVENT_ADDED_DEVICE,
 127         LIBINPUT_EVENT_REMOVED_DEVICE,
 128
 129         LIBINPUT_EVENT_DEVICE_REGISTER_CAPABILITY = 200,
 130         LIBINPUT_EVENT_DEVICE_UNREGISTER_CAPABILITY,
 131
 132         LIBINPUT_EVENT_KEYBOARD_KEY = 300,
 133
 134         LIBINPUT_EVENT_POINTER_MOTION = 400,
 135         LIBINPUT_EVENT_POINTER_MOTION_ABSOLUTE,
 136         LIBINPUT_EVENT_POINTER_BUTTON,
 137         LIBINPUT_EVENT_POINTER_AXIS,
 138
 139         LIBINPUT_EVENT_TOUCH_TOUCH = 500,
 140 };
 141
 142 struct libinput;
 143 struct libinput_device;
 144 struct libinput_seat;
 145
 146 union libinput_event_target {
 147         struct libinput *libinput;
 148         struct libinput_seat *seat;
 149         struct libinput_device *device;
 150 };
 151
 152 struct libinput_event;
 153 struct libinput_event_added_seat;
 154 struct libinput_event_removed_seat;
 155 struct libinput_event_added_device;
 156 struct libinput_event_removed_device;
 157 struct libinput_event_device_register_capability;
 158 struct libinput_event_device_unregister_capability;
 159 struct libinput_event_keyboard_key;
 160 struct libinput_event_pointer_motion;
 161 struct libinput_event_pointer_motion_absolute;
 162 struct libinput_event_pointer_button;
 163 struct libinput_event_pointer_axis;
 164 struct libinput_event_touch_touch;
 165
 166 /**
 167  * @defgroup event Acessing and destruction of events
 168  */
 169
 170 /**
 171  * @ingroup event
 172  *
 173  * Destroy the event.
 174  *
 175  * @param event An event retrieved by libinput_get_event().
 176  */
 177 void
 178 libinput_event_destroy(struct libinput_event *event);
 179
 180 /**
 181  * @ingroup event
 182  *
 183  * Get the type of the event.
 184  *
 185  * @param event An event retrieved by libinput_get_event().
 186  */
 187 enum libinput_event_type
 188 libinput_event_get_type(struct libinput_event *event);
 189
 190 /**
 191  * @ingroup event
 192  *
 193  * Get get the target union of the event.
 194  *
 195  * The valid union member depends on the event type. For global events not
 196  * related to some seat or device, the target is a libinput struct pointer.
 197  * For events associated with a seat, the target is a libinput_seat pointer
 198  * and for events associated with a device, the target is a libinput_device
 199  * pointer.
 200  *
 201  * @param event An event retrieved by libinput_get_event().
 202  */
 203 union libinput_event_target
 204 libinput_event_get_target(struct libinput_event *event);
 205
 206 /**
 207  * @defgroup event_added_seat Added seat event
 208  */
 209
 210 struct libinput_seat *
 211 libinput_event_added_seat_get_seat(struct libinput_event_added_seat *event);
 212
 213 /**
 214  * @defgroup event_removed_seat Removed seat event
 215  */
 216
 217 struct libinput_seat *
 218 libinput_event_removed_seat_get_seat(struct libinput_event_removed_seat *event);
 219
 220 /**
 221  * @defgroup event_added_device Added device event
 222  */
 223
 224 struct libinput_device *
 225 libinput_event_added_device_get_device(
 226         struct libinput_event_added_device *event);
 227
 228 /**
 229  * @defgroup event_removed_device Removed device event
 230  */
 231
 232 struct libinput_device *
 233 libinput_event_removed_device_get_device(
 234         struct libinput_event_removed_device *event);
 235
 236 /**
 237  * @defgroup event_device_register_capability Register device capability event
 238  */
 239
 240 enum libinput_device_capability
 241 libinput_event_device_register_capability_get_capability(
 242         struct libinput_event_device_register_capability *event);
 243
 244 /**
 245  * @defgroup event_device_unregister_capability Register device capability event
 246  */
 247
 248 enum libinput_device_capability
 249 libinput_event_device_unregister_capability_get_capability(
 250         struct libinput_event_device_unregister_capability *event);
 251
 252 /**
 253  * @defgroup event_keyboard_key Keyboard key event
 254  */
 255
 256 uint32_t
 257 libinput_event_keyboard_key_get_time(
 258         struct libinput_event_keyboard_key *event);
 259
 260 uint32_t
 261 libinput_event_keyboard_key_get_key(
 262         struct libinput_event_keyboard_key *event);
 263
 264 enum libinput_keyboard_key_state
 265 libinput_event_keyboard_key_get_state(
 266         struct libinput_event_keyboard_key *event);
 267
 268 /**
 269  * @defgroup event_pointer_motion Pointer motion event
 270  */
 271
 272 uint32_t
 273 libinput_event_pointer_motion_get_time(
 274         struct libinput_event_pointer_motion *event);
 275
 276 li_fixed_t
 277 libinput_event_pointer_motion_get_dx(
 278         struct libinput_event_pointer_motion *event);
 279
 280 li_fixed_t
 281 libinput_event_pointer_motion_get_dy(
 282         struct libinput_event_pointer_motion *event);
 283
 284 /**
 285  * @defgroup event_pointer_motion_absolute Absolute pointer motion event
 286  */
 287
 288 uint32_t
 289 libinput_event_pointer_motion_absolute_get_time(
 290         struct libinput_event_pointer_motion_absolute *event);
 291
 292 li_fixed_t
 293 libinput_event_pointer_motion_absolute_get_x(
 294         struct libinput_event_pointer_motion_absolute *event);
 295
 296 li_fixed_t
 297 libinput_event_pointer_motion_absolute_get_y(
 298         struct libinput_event_pointer_motion_absolute *event);
 299
 300 /**
 301  * @defgroup event_pointer_button Pointer button event
 302  */
 303
 304 uint32_t
 305 libinput_event_pointer_button_get_time(
 306         struct libinput_event_pointer_button *event);
 307
 308 uint32_t
 309 libinput_event_pointer_button_get_button(
 310         struct libinput_event_pointer_button *event);
 311
 312 enum libinput_pointer_button_state
 313 libinput_event_pointer_button_get_state(
 314         struct libinput_event_pointer_button *event);
 315
 316 /**
 317  * @defgroup event_pointer_axis Pointer axis event
 318  */
 319
 320 uint32_t
 321 libinput_event_pointer_axis_get_time(
 322         struct libinput_event_pointer_axis *event);
 323
 324 enum libinput_pointer_axis
 325 libinput_event_pointer_axis_get_axis(
 326         struct libinput_event_pointer_axis *event);
 327
 328 li_fixed_t
 329 libinput_event_pointer_axis_get_value(
 330         struct libinput_event_pointer_axis *event);
 331
 332 /**
 333  * @defgroup event_pointer_button Pointer button event
 334  */
 335
 336 uint32_t
 337 libinput_event_touch_touch_get_time(
 338         struct libinput_event_touch_touch *event);
 339
 340 uint32_t
 341 libinput_event_touch_touch_get_slot(
 342         struct libinput_event_touch_touch *event);
 343
 344 li_fixed_t
 345 libinput_event_touch_touch_get_x(
 346         struct libinput_event_touch_touch *event);
 347
 348 li_fixed_t
 349 libinput_event_touch_touch_get_y(
 350         struct libinput_event_touch_touch *event);
 351
 352 enum libinput_touch_type
 353 libinput_event_touch_touch_get_touch_type(
 354         struct libinput_event_touch_touch *event);
 355
 356 /**
 357  * @defgroup base Initialization and manipulation of libinput contexts
 358  */
 359
 360 struct libinput_interface {
 361         int (*open_restricted)(const char *path, int flags, void *user_data);
 362         void (*close_restricted)(int fd, void *user_data);
 363
 364         void (*get_current_screen_dimensions)(struct libinput_device *device,
 365                                               int *width,
 366                                               int *height,
 367                                               void *user_data);
 368 };
 369
 370 /**
 371  * @ingroup base
 372  *
 373  * Create a new libinput context from udev, for input devices matching
 374  * the given seat ID. New devices or devices removed will appear as events
 375  * during libinput_dispatch.
 376  *
 377  * @param interface The callback interface
 378  * @param user_data Caller-specific data passed to the various callback
 379  * interfaces.
 380  * @param udev An already initialized udev context
 381  * @param seat_id A seat identifier. This string must not be NULL.
 382  *
 383  * @return An initialize libinput context, ready to handle events or NULL on
 384  * error.
 385  */
 386 struct libinput *
 387 libinput_create_from_udev(const struct libinput_interface *interface,
 388                           void *user_data,
 389                           struct udev *udev,
 390                           const char *seat_id);
 391
 392 /**
 393  * @ingroup base
 394  *
 395  * libinput keeps a single file descriptor for all events. Call into
 396  * libinput_dispatch() if any events become available on this fd.
 397  *
 398  * @return the file descriptor used to notify of pending events.
 399  */
 400 int
 401 libinput_get_fd(struct libinput *libinput);
 402
 403 /**
 404  * @ingroup base
 405  *
 406  * Main event dispatchment function. Reads events of the file descriptors
 407  * and processes them internall. Use libinput_get_event() to retrieve the
 408  * events.
 409  *
 410  * @param libinput A previously initialized libinput context
 411  *
 412  * @return 0 on success, or a negative errno on failure
 413  * @retval -EAGAIN libinput_dispatch completed successfully but no events
 414  * are ready to read with libinput_get_event()
 415  */
 416 int
 417 libinput_dispatch(struct libinput *libinput);
 418
 419 /**
 420  * @ingroup base
 421  *
 422  * Retrieve the next event from libinput's internal event queue.
 423  *
 424  * After handling the retrieved event, the caller must destroy it using
 425  * libinput_event_destroy().
 426  *
 427  * @param libinput A previously initialized libinput context
 428  * @return The next available event, or NULL if no event is available.
 429  */
 430 struct libinput_event *
 431 libinput_get_event(struct libinput *libinput);
 432
 433 /**
 434  * @ingroup base
 435  *
 436  * @param libinput A previously initialized libinput context
 437  * @return the caller-specific data previously assigned in
 438  * libinput_create_udev().
 439  */
 440 void *
 441 libinput_get_user_data(struct libinput *libinput);
 442
 443 /**
 444  * @ingroup base
 445  *
 446  * Resume a suspended libinput context. This re-enables device
 447  * monitoring and adds existing devices.
 448  *
 449  * @param libinput A previously initialized libinput context
 450  * @see libinput_suspend
 451  *
 452  * @return 0 on success or -1 on failure
 453  */
 454 int
 455 libinput_resume(struct libinput *libinput);
 456
 457 /**
 458  * @ingroup base
 459  *
 460  * Suspend monitoring for new devices and close existing devices.
 461  * This all but terminates libinput but does keep the context
 462  * valid to be resumed with libinput_resume().
 463  *
 464  * @param libinput A previously initialized libinput context
 465  */
 466 void
 467 libinput_suspend(struct libinput *libinput);
 468
 469 /**
 470  * @ingroup base
 471  *
 472  * Destroy the libinput context.
 473  *
 474  * @param libinput A previously initialized libinput context
 475  */
 476 void
 477 libinput_destroy(struct libinput *libinput);
 478
 479 /**
 480  * @defgroup seat Initialization and manipulation of seats
 481  */
 482
 483 /**
 484  * @ingroup seat
 485  *
 486  * Increase the refcount of the seat. A seat will be freed whenever the
 487  * refcount reaches 0. This may happen during dispatch if the
 488  * seat was removed from the system. A caller must ensure to reference
 489  * the seat correctly to avoid dangling pointers.
 490  *
 491  * @param seat A previously obtained seat
 492  */
 493 void
 494 libinput_seat_ref(struct libinput_seat *seat);
 495
 496 /**
 497  * @ingroup seat
 498  *
 499  * Decrease the refcount of the seat. A seat will be freed whenever the
 500  * refcount reaches 0. This may happen during dispatch if the
 501  * seat was removed from the system. A caller must ensure to reference
 502  * the seat correctly to avoid dangling pointers.
 503  *
 504  * @param seat A previously obtained seat
 505  */
 506 void
 507 libinput_seat_unref(struct libinput_seat *seat);
 508
 509 /**
 510  * @ingroup seat
 511  *
 512  * Set caller-specific data associated with this seat. libinput does
 513  * not manage, look at, or modify this data. The caller must ensure the
 514  * data is valid.
 515  *
 516  * @param seat A previously obtained seat
 517  * @param user_data Caller-specific data pointer
 518  * @see libinput_seat_get_user_data
 519  */
 520 void
 521 libinput_seat_set_user_data(struct libinput_seat *seat, void *user_data);
 522
 523 /**
 524  * @ingroup seat
 525  *
 526  * Get the caller-specific data associated with this seat, if any.
 527  *
 528  * @param seat A previously obtained seat
 529  * @return Caller-specific data pointer or NULL if none was set
 530  * @see libinput_seat_set_user_data
 531  */
 532 void *
 533 libinput_seat_get_user_data(struct libinput_seat *seat);
 534
 535 /**
 536  * @ingroup seat
 537  *
 538  * @param seat A previously obtained seat
 539  * @return the name of this seat
 540  */
 541 const char *
 542 libinput_seat_get_name(struct libinput_seat *seat);
 543
 544 /**
 545  * @defgroup device Initialization and manipulation of input devices
 546  */
 547
 548 /**
 549  * @ingroup device
 550  *
 551  * Increase the refcount of the input device. An input device will be freed
 552  * whenever the refcount reaches 0. This may happen during dispatch if the
 553  * device was removed from the system. A caller must ensure to reference
 554  * the device correctly to avoid dangling pointers.
 555  *
 556  * @param device A previously obtained device
 557  */
 558 void
 559 libinput_device_ref(struct libinput_device *device);
 560
 561 /**
 562  * @ingroup device
 563  *
 564  * Decrease the refcount of the input device. An input device will be freed
 565  * whenever the refcount reaches 0. This may happen during dispatch if the
 566  * device was removed from the system. A caller must ensure to reference
 567  * the device correctly to avoid dangling pointers.
 568  *
 569  * @param device A previously obtained device
 570  */
 571 void
 572 libinput_device_unref(struct libinput_device *device);
 573
 574 /**
 575  * @ingroup device
 576  *
 577  * Set caller-specific data associated with this input device. libinput does
 578  * not manage, look at, or modify this data. The caller must ensure the
 579  * data is valid.
 580  *
 581  * @param device A previously obtained device
 582  * @param user_data Caller-specific data pointer
 583  * @see libinput_device_get_user_data
 584  */
 585 void
 586 libinput_device_set_user_data(struct libinput_device *device, void *user_data);
 587
 588 /**
 589  * @ingroup device
 590  *
 591  * Get the caller-specific data associated with this input device, if any.
 592  *
 593  * @param device A previously obtained device
 594  * @return Caller-specific data pointer or NULL if none was set
 595  * @see libinput_device_set_user_data
 596  */
 597 void *
 598 libinput_device_get_user_data(struct libinput_device *device);
 599
 600 /**
 601  * @ingroup device
 602  *
 603  * A device may be mapped to a single output, or all available outputs. If a
 604  * device is mapped to a single output only, a relative device may not move
 605  * beyond the boundaries of this output. An absolute device has its input
 606  * coordinates mapped to the extents of this output.
 607  *
 608  * @return the name of the output this device is mapped to, or NULL if no
 609  * output is set
 610  */
 611 const char *
 612 libinput_device_get_output_name(struct libinput_device *device);
 613
 614 /**
 615  * @ingroup device
 616  *
 617  * Get the seat associated with this input device.
 618  *
 619  * @param device A previously obtained device
 620  * @return The seat this input device belongs to
 621  */
 622 struct libinput_seat *
 623 libinput_device_get_seat(struct libinput_device *device);
 624
 625 /**
 626  * @ingroup device
 627  *
 628  * Update the LEDs on the device, if any. If the device does not have
 629  * LEDs, or does not have one or more of the LEDs given in the mask, this
 630  * function does nothing.
 631  *
 632  * @param device A previously obtained device
 633  * @param leds A mask of the LEDs to set, or unset.
 634  */
 635 void
 636 libinput_device_led_update(struct libinput_device *device,
 637                            enum libinput_led leds);
 638
 639 /**
 640  * @ingroup device
 641  *
 642  * Set the bitmask in keys to the bitmask of the keys present on the device
 643  * (see linux/input.h), up to size characters.
 644  *
 645  * @param device A current input device
 646  * @param keys An array filled with the bitmask for the keys
 647  * @param size Size of the keys array
 648  */
 649 int
 650 libinput_device_get_keys(struct libinput_device *device,
 651                          char *keys, size_t size);
 652
 653 /**
 654  * @ingroup device
 655  *
 656  * Apply the 3x3 transformation matrix to absolute device coordinates. This
 657  * matrix has no effect on relative events.
 658  *
 659  * Given a 6-element array [a, b, c, d, e, f], the matrix is applied as
 660  * @code
 661  * [ a  b  c ]   [ x ]
 662  * [ d  e  f ] * [ y ]
 663  * [ 0  0  1 ]   [ 1 ]
 664  * @endcode
 665  */
 666 void
 667 libinput_device_calibrate(struct libinput_device *device,
 668                           float calibration[6]);
 669
 670 /**
 671  * @ingroup device
 672  *
 673  * Check if the given device has the specified capability
 674  *
 675  * @return 1 if the given device has the capability or 0 if not
 676  */
 677 int
 678 libinput_device_has_capability(struct libinput_device *device,
 679                                enum libinput_device_capability capability);
 680
 681 #endif /* LIBINPUT_H */