lvgl 9虚拟键盘控件 (lv_keyboard) 使用指南-EW帮帮网

文章目录

简介

lv_keyboard 是 LittlevGL 提供的一个虚拟键盘控件，适用于在图形界面中输入文本。与按钮矩阵类似，虚拟键盘预定义了多个键位布局，支持多种模式和自定义键位映射，能够满足各种文本输入需求。通过与文本区域 (Text Area) 的结合，键盘能够自动将输入的字符传送到指定区域。

核心功能

多种输入模式：提供大写字母、小写字母、数字、特殊字符等多种键盘布局。
键位弹出层：支持按键弹出层效果，增强用户输入体验。
自定义键位映射：可以根据需要配置自定义的键盘布局。
文本区域关联：自动将输入的字符填充到指定的文本区域。
事件驱动：通过事件机制处理按键点击、提交、取消等操作。

样式部分

`LV_PART_MAIN`

LV_PART_MAIN 部分表示虚拟键盘的背景部分，使用标准的背景样式属性。

`LV_PART_ITEMS`

LV_PART_ITEMS 部分表示按键（按钮），可以设置标准的背景样式属性以及文字样式属性。

使用方法

1. 设置键盘模式

lv_keyboard 支持多种输入模式，根据不同的需求，可以选择不同的布局模式：

LV_KEYBOARD_MODE_TEXT_LOWER：显示小写字母。
LV_KEYBOARD_MODE_TEXT_UPPER：显示大写字母（默认模式）。
LV_KEYBOARD_MODE_TEXT_SPECIAL：显示特殊字符。
LV_KEYBOARD_MODE_NUMBER：显示数字、加减符号和小数点。
LV_KEYBOARD_MODE_USER_1 到 LV_KEYBOARD_MODE_USER_4：自定义模式。

可以通过 lv_keyboard_set_mode(kb, mode) 函数手动切换模式。例如：

lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_TEXT_UPPER);  // 设置为大写字母模式

2. 设置文本区域

可以将一个文本区域控件与键盘关联，自动将按下的字符输入到该文本区域。使用 lv_keyboard_set_textarea(kb, ta) 函数设置文本区域：

lv_keyboard_set_textarea(kb, ta);  // 将键盘与文本区域 ta 关联

3. 启用按键弹出层

类似于 Android 和 iOS 系统中的键盘，lv_keyboard 支持按键弹出层效果（例如，当按下某个符号键时，会弹出该符号的变体）。要启用此功能，可以使用以下函数：

lv_keyboard_set_popovers(kb, true);  // 启用按键弹出层

请注意，弹出层仅对生成符号的键有效。如果使用自定义键位映射，则需要为希望启用弹出层的按键设置 LV_BUTTONMATRIX_CTRL_POPOVER 标志。

另外，弹出层仅是一个视觉效果，当前不支持选择附加字符（如重音符号等）。

4. 设置自定义键位映射

可以通过 lv_keyboard_set_map(kb, mode, kb_map, kb_ctrl) 设置自定义的键位映射。这里的 kb_map 表示键位布局，kb_ctrl 表示键位控制选项。例如，可以为每个模式指定一个不同的键位映射：

lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_TEXT_UPPER, my_uppercase_map, my_controls);

在键位映射中，您可以使用以下特殊符号来定义按键行为：

LV_SYMBOL_OK：点击“OK”按钮时，触发 LV_EVENT_READY 事件。
LV_SYMBOL_CLOSE 或 LV_SYMBOL_KEYBOARD：点击“关闭”按钮时，触发 LV_EVENT_CANCEL 事件。
LV_SYMBOL_BACKSPACE：删除上一个字符。
LV_SYMBOL_LEFT 和 LV_SYMBOL_RIGHT：移动光标。
LV_SYMBOL_NEW_LINE：换行。

5. 事件

lv_keyboard 支持以下几种事件：

LV_EVENT_VALUE_CHANGED：当按下、释放或长按某个键时触发，事件数据为按键的 ID。
LV_EVENT_READY：点击“OK”按钮时触发。
LV_EVENT_CANCEL：点击“关闭”或“键盘”按钮时触发。

默认的事件处理函数是 lv_keyboard_def_event_cb()，它会自动处理按钮点击、模式切换、文本区域的输入等操作。如果需要自定义处理，可以替换默认事件处理函数。

lv_obj_add_event_cb(kb, my_keyboard_event_handler, LV_EVENT_VALUE_CHANGED, NULL);  // 添加自定义事件处理函数

6. 键位操作

在虚拟键盘中，用户可以通过方向键（LV_KEY_UP、LV_KEY_DOWN、LV_KEY_LEFT、LV_KEY_RIGHT）导航并选择按键，按下 LV_KEY_ENTER 键来执行所选按键的操作。

示例代码

以下示例展示了如何创建一个虚拟键盘并与文本区域关联：

#include "lvgl.h"

lv_obj_t *kb;
lv_obj_t *ta;

void create_keyboard() {
    // 创建文本区域
    ta = lv_textarea_create(lv_scr_act());
    lv_obj_set_size(ta, 200, 50);
    lv_obj_align(ta, LV_ALIGN_TOP_MID, 0, 10);

    // 创建虚拟键盘
    kb = lv_keyboard_create(lv_scr_act());
    lv_obj_align(kb, LV_ALIGN_BOTTOM_MID, 0, 0);
    lv_keyboard_set_textarea(kb, ta);  // 关联文本区域

    // 设置键盘模式
    lv_keyboard_set_mode(kb, LV_KEYBOARD_MODE_TEXT_UPPER);  // 设置为大写字母模式
}

int main() {
    lv_init();
    create_keyboard();

    while (1) {
        lv_task_handler();  // 处理任务
    }
}

总结

lv_keyboard 控件是 LittlevGL 提供的强大虚拟键盘解决方案，适用于任何需要文本输入的界面。通过预定义的键盘模式、自定义键位映射和文本区域自动填充功能，lv_keyboard 可以大大提升用户输入体验。无论是在嵌入式系统的用户界面中，还是在其他需要虚拟键盘的应用中，lv_keyboard 都能提供简单而高效的解决方案。

lvgl 9虚拟键盘控件 (lv_keyboard) 使用指南