Software keyboard refactored (#594)

Removed software keyboard in Tactility subproject (GuiService, Lvgl.cpp) and re-implemented it in TactilityKernel.

Modules/lvgl-module/CMakeLists.txt

@@ -92,6 +92,7 @@ include("${CMAKE_CURRENT_LIST_DIR}/../../Buildscripts/module.cmake")
 tactility_add_module(lvgl-module
     SRCS ${SOURCE_FILES}
     INCLUDE_DIRS include/
+    PRIV_INCLUDE_DIRS private/
     REQUIRES ${REQUIRES_LIST}
 )
 

Modules/lvgl-module/include/lvgl/devices/keyboard.h

@@ -10,6 +10,10 @@
 extern "C" {
 #endif
 
+struct LvglSoftwareKeyboard {
+    lv_obj_t* object;
+};
+
 /**
  * @brief Creates an lv_indev_t bound to the given KEYBOARD_TYPE device and registers a read callback
  * that polls the device through its KeyboardApi.
@@ -32,6 +36,109 @@ error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev
  */
 void lvgl_keyboard_remove(lv_indev_t* indev);
 
+/**
+ * @brief Assigns the indev to the shared keyboard input group, so it can drive focus
+ * navigation and input for focused widgets.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_keyboard_enable(lv_indev_t* indev);
+
+/**
+ * @brief Detaches the indev from the shared keyboard input group.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_keyboard_disable(lv_indev_t* indev);
+
+/**
+ * @brief Wires a textarea up to the on-screen keyboard: shows it on focus, hides it on
+ * defocus/ready, and adds the textarea to the keyboard's navigation group.
+ *
+ * No-op if lvgl_software_keyboard_is_enabled() is false (i.e. a hardware keyboard is present).
+ *
+ * @warning Caller must hold the LVGL lock.
+ * @param[in] keyboard the on-screen keyboard to associate with the textarea
+ * @param[in] textarea the lv_textarea_t object to wire up
+ */
+void lvgl_keyboard_add_textarea(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea);
+
+/**
+ * @brief Checks whether a ready (started) KEYBOARD_TYPE kernel device is present.
+ * @return true if a hardware keyboard device is available
+ */
+bool lvgl_hardware_keyboard_is_available();
+
+/**
+ * @brief Assigns the shared keyboard navigation group to a keypad indev that wasn't created via
+ * lvgl_keyboard_add() (e.g. a USB HID keyboard managed outside the kernel device system).
+ *
+ * @warning Caller must hold the LVGL lock. Requires the keyboard navigation group to already
+ * exist (created during LVGL module start).
+ * @param[in] device the keypad indev to attach to the navigation group
+ */
+void lvgl_hardware_keyboard_add_custom(lv_indev_t* device);
+
+/**
+ * @brief Detaches an indev previously registered with lvgl_hardware_keyboard_add_custom() and
+ * frees its associated context.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_hardware_keyboard_remove_custom(lv_indev_t* device);
+
+/**
+ * @brief Creates the on-screen keyboard widget as a hidden child of parent, and remembers it as
+ * the last constructed software keyboard (see lvgl_software_keyboard_get_last()).
+ * @warning Caller must hold the LVGL lock.
+ * @param[out] keyboard the software keyboard struct to initialize
+ * @param[in] parent the lv_obj_t that will own the keyboard widget
+ */
+void lvgl_software_keyboard_construct(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* parent);
+
+/**
+ * @brief Deletes the on-screen keyboard widget created by lvgl_software_keyboard_construct().
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_destruct(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * @brief Unhides the on-screen keyboard and binds it to the given textarea for input.
+ * @warning Caller must hold the LVGL lock.
+ * @param[in] keyboard the software keyboard to show
+ * @param[in] textarea the lv_textarea_t that receives the keyboard's input
+ */
+void lvgl_software_keyboard_show(struct LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea);
+
+/**
+ * @brief Hides the on-screen keyboard.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_hide(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * The on-screen keyboard is only shown when there is no hardware keyboard driver active.
+ * @return if we should show a on-screen keyboard for text input inside our apps
+ */
+bool lvgl_software_keyboard_is_enabled();
+
+/**
+ * @return the most recently constructed software keyboard, or one with a NULL object if none
+ * has been constructed yet (or the last one was destructed)
+ */
+struct LvglSoftwareKeyboard* lvgl_software_keyboard_get_last();
+
+/**
+ * @brief Attaches the shared keyboard navigation group to every currently registered keypad
+ * indev, so they can be used to navigate the on-screen keyboard and focused widgets.
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_activate(struct LvglSoftwareKeyboard* keyboard);
+
+/**
+ * @brief Detaches the navigation group from every currently registered keypad indev (inverse of
+ * lvgl_software_keyboard_activate()).
+ * @warning Caller must hold the LVGL lock.
+ */
+void lvgl_software_keyboard_deactivate(struct LvglSoftwareKeyboard* keyboard);
+
 #ifdef __cplusplus
 }
 #endif

Modules/lvgl-module/private/lvgl/devices/keyboard_private.h

@@ -0,0 +1,13 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+void lvgl_keyboard_on_start_lvgl();
+void lvgl_keyboard_on_stop_lvgl();
+
+#ifdef __cplusplus
+}
+#endif

Modules/lvgl-module/source/arch/lvgl_esp32.c

@@ -5,6 +5,7 @@
 
 #include <lvgl/lvgl.h>
 #include <lvgl/module.h>
+#include <lvgl/devices/keyboard_private.h>
 #include <tactility/error.h>
 #include <tactility/log.h>
 #include <tactility/time.h>
@@ -51,6 +52,10 @@ error_t lvgl_arch_start() {
     // devices and services. The latter might start adding widgets immediately.
     initialized = true;
 
+    // Must exist before devices/services are attached below, since those can
+    // immediately try to assign an indev to this group (e.g. USB HID input).
+    lvgl_keyboard_on_start_lvgl();
+
     lvgl_devices_attach();
 
     if (lvgl_module_config.on_start) lvgl_module_config.on_start();
@@ -63,8 +68,11 @@ error_t lvgl_arch_stop() {
 
     lvgl_devices_detach();
 
+    lvgl_keyboard_on_stop_lvgl();
+
     if (lvgl_port_deinit() != ESP_OK) {
-        // Call on_start again to recover
+        // Recreate what stop() above tore down, then call on_start again to recover
+        lvgl_keyboard_on_start_lvgl();
         if (lvgl_module_config.on_start) lvgl_module_config.on_start();
         return ERROR_RESOURCE;
     }

Modules/lvgl-module/source/arch/lvgl_posix.c

@@ -12,6 +12,7 @@
 
 #include <lvgl/lvgl.h>
 #include <lvgl/module.h>
+#include <lvgl/devices/keyboard_private.h>
 
 extern struct LvglModuleConfig lvgl_module_config;
 extern void lvgl_devices_attach();
@@ -118,6 +119,10 @@ error_t lvgl_arch_start() {
 
     lv_init();
 
+    // Must exist before devices/services are attached from the lvgl task below,
+    // since those can immediately try to assign an indev to this group.
+    lvgl_keyboard_on_start_lvgl();
+
     // Create the main app loop, like ESP-IDF
     BaseType_t task_result = xTaskCreate(
         lvgl_task,
@@ -147,6 +152,8 @@ error_t lvgl_arch_stop() {
         }
     }
 
+    lvgl_keyboard_on_stop_lvgl();
+
     lv_deinit();
 
     return ERROR_NONE;

Modules/lvgl-module/source/devices/keyboard.c

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-#include <lvgl/devices/keyboard.h>
-
-#include <tactility/drivers/keyboard.h>
-
-#include <stdlib.h>
-
-struct LvglKeyboardCtx {
-    struct Device* device;
-};
-
-static void lvgl_keyboard_read_cb(lv_indev_t* indev, lv_indev_data_t* data) {
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
-
-    struct KeyboardKeyData key_data = {0};
-    if (keyboard_read_key(ctx->device, &key_data) != ERROR_NONE) {
-        data->state = LV_INDEV_STATE_RELEASED;
-        data->continue_reading = false;
-        return;
-    }
-
-    // KeyboardKeyData deliberately mirrors lv_indev_data_t's key/continue_reading fields, so no translation is needed.
-    data->key = key_data.key;
-    data->state = key_data.pressed ? LV_INDEV_STATE_PRESSED : LV_INDEV_STATE_RELEASED;
-    data->continue_reading = key_data.continue_reading;
-}
-
-error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev_t** out_indev) {
-    if (device == NULL || out_indev == NULL) {
-        return ERROR_INVALID_ARGUMENT;
-    }
-    if (device_get_type(device) != &KEYBOARD_TYPE) {
-        return ERROR_INVALID_ARGUMENT;
-    }
-
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)malloc(sizeof(struct LvglKeyboardCtx));
-    if (ctx == NULL) {
-        return ERROR_OUT_OF_MEMORY;
-    }
-    ctx->device = device;
-
-    lv_indev_t* indev = lv_indev_create();
-    if (indev == NULL) {
-        free(ctx);
-        return ERROR_OUT_OF_MEMORY;
-    }
-
-    lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD);
-    lv_indev_set_read_cb(indev, lvgl_keyboard_read_cb);
-    lv_indev_set_driver_data(indev, ctx);
-    if (display != NULL) {
-        lv_indev_set_display(indev, display);
-    }
-
-    *out_indev = indev;
-    return ERROR_NONE;
-}
-
-void lvgl_keyboard_remove(lv_indev_t* indev) {
-    if (indev == NULL) {
-        return;
-    }
-
-    struct LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
-    lv_indev_delete(indev);
-    free(ctx);
-}

Modules/lvgl-module/source/devices/keyboard.cpp

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <lvgl/devices/keyboard.h>
+#include <lvgl/lvgl.h>
+
+#include <tactility/drivers/keyboard.h>
+
+#include <stdlib.h>
+#include <vector>
+
+struct LvglKeyboardCtx {
+    Device* device;
+};
+
+static LvglSoftwareKeyboard last_software_keyboard = {
+    .object = nullptr
+};
+
+static lv_group_t* keyboard_group;
+
+extern "C" {
+
+void lvgl_keyboard_on_start_lvgl() {
+    lvgl_lock();
+    keyboard_group = lv_group_create();
+    check(keyboard_group);
+    lvgl_unlock();
+}
+
+void lvgl_keyboard_on_stop_lvgl() {
+    last_software_keyboard = {
+        .object = nullptr
+    };
+
+    lvgl_lock();
+    lv_group_delete(keyboard_group);
+    lvgl_unlock();
+
+    keyboard_group = nullptr;
+}
+
+static void lvgl_keyboard_read_cb(lv_indev_t* indev, lv_indev_data_t* data) {
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(lv_indev_get_driver_data(indev));
+
+    KeyboardKeyData key_data = {};
+    if (keyboard_read_key(ctx->device, &key_data) != ERROR_NONE) {
+        data->state = LV_INDEV_STATE_RELEASED;
+        data->continue_reading = false;
+        return;
+    }
+
+    // KeyboardKeyData deliberately mirrors lv_indev_data_t's key/continue_reading fields, so no translation is needed.
+    data->key = key_data.key;
+    data->state = key_data.pressed ? LV_INDEV_STATE_PRESSED : LV_INDEV_STATE_RELEASED;
+    data->continue_reading = key_data.continue_reading;
+}
+
+error_t lvgl_keyboard_add(struct Device* device, lv_display_t* display, lv_indev_t** out_indev) {
+    if (device == NULL || out_indev == NULL) {
+        return ERROR_INVALID_ARGUMENT;
+    }
+    if (device_get_type(device) != &KEYBOARD_TYPE) {
+        return ERROR_INVALID_ARGUMENT;
+    }
+
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(malloc(sizeof(struct LvglKeyboardCtx)));
+    if (ctx == NULL) {
+        return ERROR_OUT_OF_MEMORY;
+    }
+    ctx->device = device;
+
+    lv_indev_t* indev = lv_indev_create();
+    if (indev == NULL) {
+        free(ctx);
+        return ERROR_OUT_OF_MEMORY;
+    }
+
+    lv_indev_set_type(indev, LV_INDEV_TYPE_KEYPAD);
+    lv_indev_set_read_cb(indev, lvgl_keyboard_read_cb);
+    lv_indev_set_driver_data(indev, ctx);
+    if (display != NULL) {
+        lv_indev_set_display(indev, display);
+    }
+
+    *out_indev = indev;
+    return ERROR_NONE;
+}
+
+void lvgl_keyboard_remove(lv_indev_t* indev) {
+    if (indev == NULL) {
+        return;
+    }
+
+    LvglKeyboardCtx* ctx = (struct LvglKeyboardCtx*)lv_indev_get_driver_data(indev);
+    lv_indev_delete(indev);
+    free(ctx);
+}
+
+void lvgl_keyboard_enable(lv_indev_t* indev) {
+    check(keyboard_group != nullptr);
+    lv_indev_set_group(indev, keyboard_group);
+}
+
+void lvgl_keyboard_disable(lv_indev_t* indev) {
+    lv_indev_set_group(indev, nullptr);
+}
+
+bool lvgl_hardware_keyboard_is_available() {
+    Device* keyboard_device;
+    if (device_get_first_active_by_type(&KEYBOARD_TYPE, &keyboard_device) != ERROR_NONE) {
+        return false;
+    }
+
+    device_put(keyboard_device);
+    return true;
+}
+
+void lvgl_hardware_keyboard_add_custom(lv_indev_t* indev) {
+    LvglKeyboardCtx* ctx = static_cast<struct LvglKeyboardCtx*>(malloc(sizeof(struct LvglKeyboardCtx)));
+    if (ctx == nullptr) {
+        return;
+    }
+
+    ctx->device = nullptr;
+    lv_indev_set_driver_data(indev, ctx);
+
+    lvgl_keyboard_enable(indev);
+}
+
+void lvgl_hardware_keyboard_remove_custom(lv_indev_t* indev) {
+    lvgl_keyboard_disable(indev);
+    auto* data = lv_indev_get_driver_data(indev);
+    lv_indev_set_driver_data(indev, nullptr);
+    free(data); // LvglKeyboardCtx*
+}
+
+static void textarea_show_keyboard(lv_event_t* event) {
+    lv_obj_t* target = lv_event_get_current_target_obj(event);
+    if (last_software_keyboard.object != nullptr) {
+        lvgl_software_keyboard_show(&last_software_keyboard, target);
+        lv_obj_scroll_to_view(target, LV_ANIM_ON);
+    }
+}
+
+static void textarea_hide_keyboard(lv_event_t* event) {
+    if (last_software_keyboard.object != nullptr) {
+        lvgl_software_keyboard_hide(&last_software_keyboard);
+    }
+}
+
+void lvgl_software_keyboard_construct(LvglSoftwareKeyboard* keyboard, lv_obj_t* parent) {
+    keyboard->object = lv_keyboard_create(parent);
+    lv_obj_add_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+    last_software_keyboard = *keyboard;
+}
+
+void lvgl_software_keyboard_destruct(LvglSoftwareKeyboard* keyboard) {
+    check(keyboard->object);
+
+    lv_obj_delete(keyboard->object);
+    keyboard->object = nullptr;
+
+    last_software_keyboard = *keyboard;
+}
+
+void lvgl_software_keyboard_show(LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea) {
+    assert(keyboard->object != nullptr);
+    lv_obj_clear_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+    lv_keyboard_set_textarea(keyboard->object, textarea);
+}
+
+void lvgl_software_keyboard_hide(LvglSoftwareKeyboard* keyboard) {
+    assert(keyboard->object != nullptr);
+    lv_obj_add_flag(keyboard->object, LV_OBJ_FLAG_HIDDEN);
+}
+
+bool lvgl_software_keyboard_is_enabled() {
+    return !lvgl_hardware_keyboard_is_available();
+}
+
+LvglSoftwareKeyboard* lvgl_software_keyboard_get_last() {
+    return &last_software_keyboard;
+}
+
+void lvgl_keyboard_add_textarea(LvglSoftwareKeyboard* keyboard, lv_obj_t* textarea) {
+    if (lvgl_software_keyboard_is_enabled()) {
+        lv_obj_add_event_cb(textarea, textarea_show_keyboard, LV_EVENT_FOCUSED, nullptr);
+        lv_obj_add_event_cb(textarea, textarea_hide_keyboard, LV_EVENT_DEFOCUSED, nullptr);
+        lv_obj_add_event_cb(textarea, textarea_hide_keyboard, LV_EVENT_READY, nullptr);
+
+        // lv_obj_t auto-remove themselves from the group when they are destroyed (last checked in LVGL 8.3)
+        lv_group_add_obj(keyboard_group, textarea);
+
+        lvgl_software_keyboard_activate(keyboard);
+    }
+}
+
+void lvgl_software_keyboard_activate(LvglSoftwareKeyboard* keyboard) {
+    auto* indev = lv_indev_get_next(nullptr);
+    check(keyboard_group);
+    while (indev) {
+        if (lv_indev_get_type(indev) == LV_INDEV_TYPE_KEYPAD) {
+            lv_indev_set_group(indev, keyboard_group);
+        }
+        indev = lv_indev_get_next(indev);
+    }
+}
+
+void lvgl_software_keyboard_deactivate(LvglSoftwareKeyboard* keyboard) {
+    auto* indev = lv_indev_get_next(nullptr);
+    while (indev) {
+        if (lv_indev_get_type(indev) == LV_INDEV_TYPE_KEYPAD) {
+            lv_indev_set_group(indev, nullptr);
+        }
+        indev = lv_indev_get_next(indev);
+    }
+}
+
+}