summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2017-06-09 14:35:51 -0400
committerMike Blumenkrantz <zmike@osg.samsung.com>2017-06-09 14:35:51 -0400
commit6a5695b465fe7496e0ee10d9a473053d76180c54 (patch)
tree486fed3b3f6ee3cbccb8bb1efe38ee5dd40b0453 /src
parentca66a9fa0de567086fc2c1405ca1980357a88db1 (diff)
elput: Document how keyboard events are processed
Summary: Add some light function docs and code comments to explain the steps followed in processing hardware events for keyboard hits into actual printable characters. While this is internal functionality, the process is important and involves a couple external dependencies (libinput and libxkbcommon) so documenting this flow may help future developers avoid introducing bugs. Signed-off-by: Bryce Harrington <bryce@osg.samsung.com> Reviewers: zmike Subscribers: cedric, jpeg Differential Revision: https://phab.enlightenment.org/D4953
Diffstat (limited to 'src')
-rw-r--r--src/lib/elput/elput_evdev.c51
1 files changed, 51 insertions, 0 deletions
diff --git a/src/lib/elput/elput_evdev.c b/src/lib/elput/elput_evdev.c
index 0a5c018dc6..4364d48c75 100644
--- a/src/lib/elput/elput_evdev.c
+++ b/src/lib/elput/elput_evdev.c
@@ -162,6 +162,15 @@ _keyboard_info_destroy(Elput_Keyboard_Info *info)
162 free(info); 162 free(info);
163} 163}
164 164
165/**
166 * @brief Creates the XKB context and keymap.
167 *
168 * @param kbd The keyboard config to be set up for XKB.
169 * @return EINA_TRUE if build successful, EINA_FALSE otherwise.
170 *
171 * Sets default settings for the keyboard if not set by the system.
172 * Assumes evdev rules, with a pc105 model keyboard and US key layout.
173 */
165static Eina_Bool 174static Eina_Bool
166_keyboard_global_build(Elput_Keyboard *kbd) 175_keyboard_global_build(Elput_Keyboard *kbd)
167{ 176{
@@ -220,6 +229,10 @@ _keyboard_compose_init(Elput_Keyboard *kbd)
220 kbd->compose_state = NULL; 229 kbd->compose_state = NULL;
221} 230}
222 231
232/**
233 * Create a new keyboard object for the seat, initialized
234 * to the given keymap.
235 */
223static Eina_Bool 236static Eina_Bool
224_keyboard_init(Elput_Seat *seat, struct xkb_keymap *keymap) 237_keyboard_init(Elput_Seat *seat, struct xkb_keymap *keymap)
225{ 238{
@@ -298,6 +311,12 @@ _event_free(void *dev, void *ev)
298 free(ev); 311 free(ev);
299} 312}
300 313
314/**
315 * Creates an event key object and generates a corresponding event.
316 *
317 * An ECORE_EVENT_KEY_DOWN event is generated on state
318 * LIBINPUT_KEY_STATE_PRESSED, or ECORE_EVENT_KEY_DOWN otherwise.
319 */
301static void 320static void
302_keyboard_key_send(Elput_Device *dev, enum libinput_key_state state, const char *keyname, const char *key, const char *compose, unsigned int code, unsigned int timestamp) 321_keyboard_key_send(Elput_Device *dev, enum libinput_key_state state, const char *keyname, const char *key, const char *compose, unsigned int code, unsigned int timestamp)
303{ 322{
@@ -603,6 +622,9 @@ process_key_press(xkb_keysym_t sym, Elput_Keyboard *kbd)
603 return sym; 622 return sym;
604} 623}
605 624
625/**
626 * Retrieve the string name ('q', 'bracketleft', etc.) for a given key symbol.
627 */
606static void 628static void
607_elput_symbol_rep_find(xkb_keysym_t keysym, char *buffer, int size, unsigned int code) 629_elput_symbol_rep_find(xkb_keysym_t keysym, char *buffer, int size, unsigned int code)
608{ 630{
@@ -622,6 +644,17 @@ _elput_symbol_rep_find(xkb_keysym_t keysym, char *buffer, int size, unsigned int
622 snprintf(buffer, size, "Keycode-%u", code); 644 snprintf(buffer, size, "Keycode-%u", code);
623} 645}
624 646
647/**
648 * Handle keyboard events emitted by libinput.
649 *
650 * Processes a single key pressed / released event from libinput. The
651 * key code will be remapped to another code if one has been registered
652 * (see elput_input_key_remap_enable()), and then XKB notified of the
653 * keyboard status change. XKB translates the key code into the
654 * appropriate symbol for the current keyboard layout. Compose
655 * translation is performed, if appropriate. An up or down event is
656 * then generated for the processed key via _keyboard_key_send().
657 */
625static void 658static void
626_keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *event) 659_keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *event)
627{ 660{
@@ -642,6 +675,7 @@ _keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *e
642 kbd = _evdev_keyboard_get(dev->seat); 675 kbd = _evdev_keyboard_get(dev->seat);
643 if (!kbd) return; 676 if (!kbd) return;
644 677
678 /* Retrieve details about the event from libinput */
645 state = libinput_event_keyboard_get_key_state(event); 679 state = libinput_event_keyboard_get_key_state(event);
646 kbd->key_count = count = libinput_event_keyboard_get_seat_key_count(event); 680 kbd->key_count = count = libinput_event_keyboard_get_seat_key_count(event);
647 681
@@ -650,16 +684,24 @@ _keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *e
650 ((state == LIBINPUT_KEY_STATE_RELEASED) && (count != 0))) 684 ((state == LIBINPUT_KEY_STATE_RELEASED) && (count != 0)))
651 return; 685 return;
652 686
687 /* Retrieve the code and remap it if a remap for it has been registered */
653 code = libinput_event_keyboard_get_key(event); 688 code = libinput_event_keyboard_get_key(event);
654 code = _keyboard_remapped_key_get(dev, code) + 8; 689 code = _keyboard_remapped_key_get(dev, code) + 8;
655 690
656 timestamp = libinput_event_keyboard_get_time(event); 691 timestamp = libinput_event_keyboard_get_time(event);
657 692
693 /* Update the XKB keyboard state for the key that was pressed or released */
658 if (state == LIBINPUT_KEY_STATE_PRESSED) 694 if (state == LIBINPUT_KEY_STATE_PRESSED)
659 xkb_state_update_key(kbd->state, code, XKB_KEY_DOWN); 695 xkb_state_update_key(kbd->state, code, XKB_KEY_DOWN);
660 else 696 else
661 xkb_state_update_key(kbd->state, code, XKB_KEY_UP); 697 xkb_state_update_key(kbd->state, code, XKB_KEY_UP);
662 698
699 /* Apply the current keyboard state to translate the code for the key
700 * that was struck into its effective symbol (after applying
701 * modifiers like CAPSLOCK and so on). We also use the maskless
702 * keyboard state to lookup the underlying symbol name (i.e. without
703 * applying modifiers).
704 */
663 nsyms = xkb_key_get_syms(kbd->state, code, &syms); 705 nsyms = xkb_key_get_syms(kbd->state, code, &syms);
664 if (nsyms == 1) sym = syms[0]; 706 if (nsyms == 1) sym = syms[0];
665 sym_name = xkb_state_key_get_one_sym(kbd->maskless_state, code); 707 sym_name = xkb_state_key_get_one_sym(kbd->maskless_state, code);
@@ -667,12 +709,17 @@ _keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *e
667 if (state == LIBINPUT_KEY_STATE_PRESSED) 709 if (state == LIBINPUT_KEY_STATE_PRESSED)
668 sym = process_key_press(sym, kbd); 710 sym = process_key_press(sym, kbd);
669 711
712 /* Lookup the textual name ('q', 'space', 'bracketleft', etc.) of the
713 * symbol and of the symbol name.
714 */
670 _elput_symbol_rep_find(sym, key, sizeof(key), code); 715 _elput_symbol_rep_find(sym, key, sizeof(key), code);
671 _elput_symbol_rep_find(sym_name, keyname, sizeof(keyname), code); 716 _elput_symbol_rep_find(sym_name, keyname, sizeof(keyname), code);
672 717
718 /* If no keyname was found, name it "Keycode-NNN" */
673 if (keyname[0] == '\0') 719 if (keyname[0] == '\0')
674 snprintf(keyname, sizeof(keyname), "Keycode-%u", code); 720 snprintf(keyname, sizeof(keyname), "Keycode-%u", code);
675 721
722 /* If Shift key is active, downcase the keyname's first letter */
676 if (xkb_state_mod_index_is_active(kbd->state, kbd->info->mods.shift, 723 if (xkb_state_mod_index_is_active(kbd->state, kbd->info->mods.shift,
677 XKB_STATE_MODS_EFFECTIVE)) 724 XKB_STATE_MODS_EFFECTIVE))
678 { 725 {
@@ -680,9 +727,13 @@ _keyboard_key(struct libinput_device *idevice, struct libinput_event_keyboard *e
680 keyname[0] = tolower(keyname[0]); 727 keyname[0] = tolower(keyname[0]);
681 } 728 }
682 729
730 /* Update the seat's modifiers to match what's active in the kbd */
683 _keyboard_modifiers_update(kbd, dev->seat); 731 _keyboard_modifiers_update(kbd, dev->seat);
684 732
733 /* Translate the key symbol into a printable character in Unicode (UTF-8) format */
685 _keyboard_keysym_translate(sym, dev->seat->modifiers, compose, sizeof(compose)); 734 _keyboard_keysym_translate(sym, dev->seat->modifiers, compose, sizeof(compose));
735
736 /* Issue the appropriate key up or down event with all related key data */
686 _keyboard_key_send(dev, state, keyname, key, compose, code, timestamp); 737 _keyboard_key_send(dev, state, keyname, key, compose, code, timestamp);
687 738
688 if ((kbd->pending_keymap) && (count == 0)) 739 if ((kbd->pending_keymap) && (count == 0))