LVGL-键盘

lv_keyboard_create

用于创建虚拟键盘控件的函数，通常用于触摸屏设备的文本输入场景

lv_obj_t * lv_keyboard_create(lv_obj_t * parent);
//parent: 指向父容器对象的指针
//ret:返回指向新创建的键盘对象的指针，如果创建失败则返回 NULL

lv_keyboard_set_textarea

用于将键盘控件与文本框控件关联的关键函数，它建立了键盘输入与文本框显示之间的桥梁

void lv_keyboard_set_textarea(lv_obj_t * kb, lv_obj_t * ta);
//kb: 指向键盘对象的指针，必须是通过 lv_keyboard_create 创建的键盘控件
//ta: 指向文本框对象的指针，必须是通过 lv_textarea_create 创建的文本框控件

lv_keyboard_set_mode

用于设置虚拟键盘输入模式的函数，它允许开发者根据不同的输入需求切换键盘布局

void lv_keyboard_set_mode(lv_obj_t * kb, lv_keyboard_mode_t mode);
//kb: 指向键盘对象的指针，必须是通过 lv_keyboard_create 创建的键盘控件
/*
mode: 要设置的键盘模式，可以是以下枚举值之一：
LV_KEYBOARD_MODE_TEXT_LOWER: 小写字母键盘
LV_KEYBOARD_MODE_TEXT_UPPER: 大写字母键盘（默认模式）
LV_KEYBOARD_MODE_SPECIAL: 特殊字符键盘
LV_KEYBOARD_MODE_NUMBER: 数字键盘（包含0-9、+/-和小数点）
LV_KEYBOARD_MODE_USER_1 到 LV_KEYBOARD_MODE_USER_4: 用户自定义模式
*/

lv_keyboard_set_popovers

用于控制键盘按键按下时是否显示弹出提示框（popover）的函数

void lv_keyboard_set_popovers(lv_obj_t * kb, bool en);
//kb: 指向键盘对象的指针
//en: 布尔值，true 表示启用弹出提示框，false 表示禁用

lv_keyboard_set_map

用于自定义键盘布局的核心函数，它允许开发者完全重定义键盘的按键排列和功能

void lv_keyboard_set_map(lv_obj_t * kb, 
                        lv_keyboard_mode_t mode, 
                        const char * map[], 
                        const lv_btnmatrix_ctrl_t ctrl_map[]);
//kb: 指向键盘对象的指针
//mode: 要设置的键盘模式
//map: 指向字符串数组的指针，描述按键布局，使用\n表示换行
//ctrl_map: (可选)指向控制属性数组的指针，定义每个按键的特殊属性

lv_keyboard_get_textarea

用于获取与键盘控件关联的文本框对象的函数，它可以帮助开发者查询当前键盘正在操作的文本框。

lv_obj_t * lv_keyboard_get_textarea(const lv_obj_t * kb);
//kb: 指向键盘对象的指针
//ret:返回当前与键盘关联的文本框对象指针，如果没有关联的文本框，则返回 NULL 

lv_keyboard_get_mode

用于获取键盘当前输入模式的函数，它可以帮助开发者查询键盘的当前状态，以便进行相应的逻辑处理。

lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t * kb);
//kb: 指向键盘对象的指针
/*
返回当前键盘的模式，可能的枚举值包括：
LV_KEYBOARD_MODE_TEXT_LOWER: 小写字母键盘
LV_KEYBOARD_MODE_TEXT_UPPER: 大写字母键盘
LV_KEYBOARD_MODE_SPECIAL: 特殊字符键盘
LV_KEYBOARD_MODE_NUMBER: 数字键盘
LV_KEYBOARD_MODE_USER_1 到 LV_KEYBOARD_MODE_USER_4: 用户自定义模式
*/

lv_btnmatrix_get_popovers

用于检查按钮矩阵(Button Matrix)是否启用了按键弹出提示(popover)功能的函数

bool lv_btnmatrix_get_popovers(const lv_obj_t * obj);
//obj: 指向按钮矩阵对象的指针
//ret:true: 表示已启用按键弹出提示功能，false: 表示未启用按键弹出提示功能

lv_keyboard_get_map_array

用于获取键盘当前按键映射数组的函数，它返回一个指向描述键盘布局的字符串数组的指针

const char ** lv_keyboard_get_map_array(const lv_obj_t * kb);
//kb: 指向键盘对象的指针
//ret:返回当前键盘的按键映射数组指针,数组以 NULL 或空字符串结尾,数组中的 \n 表示换行

lv_keyboard_get_selected_btn

用于获取键盘当前被选中/按下的按钮索引的函数

uint32_t lv_keyboard_get_selected_btn(const lv_obj_t * obj);
//obj: 指向键盘对象的指针
//ret:返回当前被选中/按下的按钮的索引值（从0开始）,如果没有按钮被选中，返回值未定义

lv_keyboard_get_btn_text

用于获取键盘指定按钮文本内容的函数

const char * lv_keyboard_get_btn_text(const lv_obj_t * obj, uint32_t btn_id);
//obj: 指向键盘对象的指针
//btn_id: 要查询的按钮索引值
//ret:返回指向按钮文本的常量字符串指针,如果索引无效或按钮无文本，可能返回空指针或空字符串

lv_keyboard_def_event_cb

键盘控件的默认事件处理回调函数，它负责处理键盘的基本交互逻辑，包括按键输入、模式切换和与文本框的交互。

void lv_keyboard_def_event_cb(lv_obj_t * kb, lv_event_t * e);
//kb: 指向键盘对象的指针
//e: 指向事件结构的指针，包含事件类型和相关信息

static void ta_event_cb(lv_event_t * e)
{
    // 获取当前事件类型
    lv_event_code_t code = lv_event_get_code(e);
    
    // 获取触发事件的文本框对象
    lv_obj_t * ta = lv_event_get_target(e);
    
    // 获取通过事件传递的用户数据（这里是键盘对象）
    lv_obj_t * kb = lv_event_get_user_data(e);
    
    // 处理文本框获得焦点事件
    if(code == LV_EVENT_FOCUSED) {
        // 将键盘与当前获得焦点的文本框关联
        lv_keyboard_set_textarea(kb, ta);
        
        // 清除键盘的隐藏标志，使其可见
        lv_obj_clear_flag(kb, LV_OBJ_FLAG_HIDDEN);
    }

    // 处理文本框失去焦点事件
    if(code == LV_EVENT_DEFOCUSED) {
        // 解除键盘与文本框的关联
        lv_keyboard_set_textarea(kb, NULL);
        
        // 设置键盘的隐藏标志，使其不可见
        lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN);
    }
}
void lv_example_keyboard_1(void)
{
    /* 创建一个键盘对象，父对象为当前活动屏幕 */
    lv_obj_t * kb = lv_keyboard_create(lv_scr_act());

    /* 创建第一个文本框 */
    lv_obj_t * ta;
    ta = lv_textarea_create(lv_scr_act());  // 创建文本框
    
    // 将文本框对齐到屏幕左上角，偏移(10,10)
    lv_obj_align(ta, LV_ALIGN_TOP_LEFT, 10, 10);
    
    // 为文本框添加事件回调，传递键盘对象作为用户数据
    lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_ALL, kb);
    
    // 设置文本框的占位文本（提示文字）
    lv_textarea_set_placeholder_text(ta, "Hello");
    
    // 设置文本框大小为140x80像素
    lv_obj_set_size(ta, 140, 80);

    /* 创建第二个文本框 */
    ta = lv_textarea_create(lv_scr_act());  // 创建第二个文本框
    
    // 将文本框对齐到屏幕右上角，偏移(-10,10)
    lv_obj_align(ta, LV_ALIGN_TOP_RIGHT, -10, 10);
    
    // 为第二个文本框添加相同的事件回调
    lv_obj_add_event_cb(ta, ta_event_cb, LV_EVENT_ALL, kb);
    
    // 设置第二个文本框的大小
    lv_obj_set_size(ta, 140, 80);

    /* 初始时将键盘与第二个文本框关联 */
    lv_keyboard_set_textarea(kb, ta);
}