14. 键盘部件
一、键盘部件
键盘部件本质上是一个特殊的按钮矩阵，它具有预定义的键映射和逻辑处理，从而实现文本的输入功能。键盘部件与按钮矩阵的组成类似，一共有两个部分：主体背景（LV_PART_MAIN）和 按钮（LV_PART_ITEMS）。
LVGL 官方提供了一些与键盘部件相关 API。
lv_obj_t * lv_keyboard_create(lv_obj_t * parent); // 创建键盘部件
void lv_keyboard_set_textarea(lv_obj_t * obj, lv_obj_t * ta); // 指定文本区域
lv_obj_t * lv_keyboard_get_textarea(const lv_obj_t * obj); // 获取键盘关联的文本区域对象
void lv_keyboard_set_mode(lv_obj_t * obj, lv_keyboard_mode_t mode); // 设置键盘模式
lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t * obj); // 获取键盘模式
void lv_keyboard_set_popovers(lv_obj_t * obj, bool en); // 设置按键弹窗
bool lv_buttonmatrix_get_popovers(const lv_obj_t * obj); // 判断是否启用按键弹窗
void lv_keyboard_set_map(lv_obj_t * obj, lv_keyboard_mode_t mode, const char * map[], const lv_buttonmatrix_ctrl_t ctrl_map[]); // 设置一个新的按键映射
static inline const char ** lv_keyboard_get_map_array(const lv_obj_t * kb); // 获取键盘的当前按键映射
static inline uint32_t lv_keyboard_get_selected_button(const lv_obj_t * obj); // 获取按下的按键索引
static inline const char * lv_keyboard_get_button_text(const lv_obj_t * obj, uint32_t btn_id); // 获取按下的按键文本
void lv_keyboard_def_event_cb(lv_event_t * e); // 添加字符到文本区域和改变映射
我们可以使用 lv_keyborad_create() 函数 创建键盘部件。
/**
* @brief 创建键盘部件
*
* @param parent 指向父部件的指针
* @return lv_obj_t* 指向键盘部件的指针
*/
lv_obj_t * lv_keyboard_create(lv_obj_t * parent);
在默认的情况下，键盘部件没有与任何输入框关联，此时，即使用户输入内容，这些内容并不会更新到输入框中，因此，如果我们想要把键盘输入的内容传入在文本区域部件当中，就必须调用 lv_keyboard_set_textarea() 函数，把键盘和文本区域部件关联起来。
/**
* @brief 指定文本区域
*
* @param obj 指向键盘部件的指针
* @param ta 指向文本区域部件的指针
*/
void lv_keyboard_set_textarea(lv_obj_t * obj, lv_obj_t * ta);
键盘部件内嵌了多种输入模式：大写字母、小写字母和特殊字符等，用户可以触摸相应的按键进行模式切换。如果用户需要手动 切换输入模式，可调用 lv_keyboard_set_mode() 函数进行设置。
/**
* @brief 设置键盘模式
*
* @param obj 指向键盘部件的指针
* @param mode 键盘的模式选择
*/
void lv_keyboard_set_mode(lv_obj_t * obj, lv_keyboard_mode_t mode);
该函数的第二个形参代表要切换的输入模式，这些模式的枚举如下所示：
enum _lv_keyboard_mode_t {
LV_KEYBOARD_MODE_TEXT_LOWER, // 小写字母键盘
LV_KEYBOARD_MODE_TEXT_UPPER, // 大写字母键盘
LV_KEYBOARD_MODE_SPECIAL, // 特殊字符键盘
LV_KEYBOARD_MODE_NUMBER, // 数字键盘
LV_KEYBOARD_MODE_USER_1, // 自定义模式1
LV_KEYBOARD_MODE_USER_2, // 自定义模式2
LV_KEYBOARD_MODE_USER_3, // 自定义模式3
LV_KEYBOARD_MODE_USER_4, // 自定义模式4
#if LV_USE_ARABIC_PERSIAN_CHARS == 1
LV_KEYBOARD_MODE_TEXT_ARABIC
#endif
};
按键弹窗指的是当用户按下键盘中的某一个按键时，突出显示该按键的文本。用户需要开启按键弹窗，可调用 lv_keyboard_set_popovers() 函数进行设置，该函数的第二个形参为 true，则代表启用按键弹窗。
/**
* @brief 设置按键弹窗
*
* @param obj 指向键盘部件的指针
* @param en true: 启动弹窗; false: 禁用弹窗
*/
void lv_keyboard_set_popovers(lv_obj_t * obj, bool en);
如果我们不满足默认的键盘映射模式，我们还可以使用 lv_keyboard_set_map() 函数设置一个新的按键映射。
/**
* @brief 设置一个新的按键映射
*
* @param obj 指向键盘部件的指针
* @param mode 键盘的模式选择
* @param map 指向描述映射的字符串数组的指针
* @param ctrl_map 要设置新的map
*/
void lv_keyboard_set_map(lv_obj_t * obj, lv_keyboard_mode_t mode, const char * map[], const lv_buttonmatrix_ctrl_t ctrl_map[]);
二、实验例程
int main(void)
{
HAL_Init();
System_Clock_Init(8, 336, 2, 7);
Delay_Init(168);
SPI_Simulate_Init();
// SRAM_Init();
TIM_Base_Init(&g_tim6_handle, TIM6, 83, 999);
__HAL_TIM_CLEAR_IT(&g_tim6_handle, TIM_IT_UPDATE); // 清除更新中断标志位
HAL_TIM_Base_Start_IT(&g_tim6_handle); // 使能更新中断，并启动计数器
lv_init();
lv_port_disp_init();
lv_port_indev_init();
// 测试代码
lv_obj_t *textArea = lv_textarea_create(lv_scr_act()); // 创建文本区域部件
lv_obj_align(textArea, LV_ALIGN_TOP_MID, 0, 50); // 设置文本区域部件考上居中对齐
lv_obj_t *keyBoard = lv_keyboard_create(lv_scr_act()); // 创建键盘部件
lv_keyboard_set_textarea(keyBoard, textArea); // 关联键盘部件和文本区域部件
lv_keyboard_set_popovers(keyBoard, true); // 设置键盘弹窗
lv_obj_add_event_cb(keyBoard,keyBoard_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
while (1)
{
lv_timer_handler();
Delay_ms(5);
}
return 0;
}
void keyBoard_event_cb(lv_event_t *e)
{
lv_event_code_t code = lv_event_get_code(e); // 获取事件的触发类型
lv_obj_t *target = lv_event_get_target(e); // 获取事件的触发源
uint32_t id = 0;
const char *text;
if (code == LV_EVENT_VALUE_CHANGED)
{
id = lv_btnmatrix_get_selected_btn(target); // 获取当前选中的按键的索引
text = lv_keyboard_get_button_text(target, id); // 获取当前选中的按键的文本
if (strcmp(text, LV_SYMBOL_KEYBOARD) == 0) // 判断是否为键盘按键
{
if (lv_keyboard_get_mode(target) == LV_KEYBOARD_MODE_NUMBER) // 判断当前键盘模式是否为数字键盘
{
lv_keyboard_set_mode(target, LV_KEYBOARD_MODE_TEXT_LOWER); // 如果是数字键盘，切换为小写字母键盘
}
else
{
lv_keyboard_set_mode(target, LV_KEYBOARD_MODE_NUMBER); // 如果是其它键盘模式，切换为数字键盘
}
}
}
}
