键盘 (lv_keyboard)¶

概述¶

键盘对象是一个特殊的按钮矩阵，具有预定义的键映射和其他功能，用于实现虚拟键盘以在文本区域中输入文本。

部件和样式¶

与按钮矩阵类似，键盘由两个部件组成：

LV_PART_MAIN 主部件。使用所有典型的背景属性。
LV_PART_ITEMS 按钮。也使用所有典型的背景属性以及文本属性。

用法¶

模式¶

键盘具有以下模式：

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 用户定义模式

TEXT 模式的布局包含用于更改模式的按钮。

要手动设置模式，请使用 lv_keyboard_set_mode(kb, mode)。默认模式为 LV_KEYBOARD_MODE_TEXT_UPPER。

分配文本区域¶

可以将文本区域分配给键盘，以便自动将点击的字符放入其中。使用 lv_keyboard_set_textarea(kb, ta) 分配文本区域。

键弹出¶

要启用按键弹出效果（类似于常见的 Android 和 iOS 键盘），请使用 lv_keyboard_set_popovers(kb, true)。默认控制映射已预配置，仅在生成符号的按键上显示弹出效果，而不是例如空格键。如果使用自定义键映射，请为希望显示弹出效果的所有按键设置 LV_BTNMATRIX_CTRL_POPOVER 标志。

注意，顶部行的按键弹出效果会绘制在小部件边界之外。为此，请在键盘顶部预留额外的空白空间，或者确保键盘在其顶部边界相邻的小部件之后添加，以便弹出效果可以覆盖这些小部件。

目前，按键弹出效果仅是视觉效果，尚不支持选择附加字符（如重音符）。

新键映射¶

可以使用 lv_keyboard_set_map(kb, map) 和 lv_keyboard_set_ctrl_map(kb, ctrl_map) 指定键盘的新映射（布局）。了解更多关于按钮矩阵对象的信息。请记住，使用以下关键字将具有与原始映射相同的效果：

LV_SYMBOL_OK 应用。
LV_SYMBOL_CLOSE 或 LV_SYMBOL_KEYBOARD 关闭。
LV_SYMBOL_BACKSPACE 删除左侧字符。
LV_SYMBOL_LEFT 光标左移。
LV_SYMBOL_RIGHT 光标右移。
LV_SYMBOL_NEW_LINE 换行。
"ABC" 加载大写字母映射。
"abc" 加载小写字母映射。
"1#" 加载数字映射。

事件¶

LV_EVENT_VALUE_CHANGED 当按钮被按下/释放或长按后重复时发送。事件数据设置为按下/释放按钮的 ID。
LV_EVENT_READY - 点击确定按钮。
LV_EVENT_CANCEL - 点击关闭按钮。

键盘具有一个默认事件处理程序回调，称为 lv_keyboard_def_event_cb，用于处理按钮按下、映射更改、分配的文本区域等。如果需要，可以移除它并替换为自定义事件处理程序。

Note

在 8.0 及更高版本中，为键盘添加事件处理程序不会移除默认事件处理程序。此行为与 v7 不同，在 v7 中，添加事件处理程序总是会替换之前的事件处理程序。

了解更多关于事件的信息。

按键¶

LV_KEY_RIGHT/UP/LEFT/RIGHT 在按钮之间导航并选择一个按钮。
LV_KEY_ENTER 按下/释放选定的按钮。

了解更多关于按键的信息。

示例¶

Keyboard with text area¶

#include "../../lv_examples.h"
#if LV_USE_KEYBOARD && LV_BUILD_EXAMPLES

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)
{
    /*Create a keyboard to use it with an of the text areas*/
    lv_obj_t * kb = lv_keyboard_create(lv_scr_act());

    /*Create a text area. The keyboard will write here*/
    lv_obj_t * ta;
    ta = lv_textarea_create(lv_scr_act());
    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");
    lv_obj_set_size(ta, 140, 80);

    ta = lv_textarea_create(lv_scr_act());
    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);
}
#endif

def ta_event_cb(e,kb):
    code = e.get_code()
    ta = e.get_target()
    if code == lv.EVENT.FOCUSED:
        kb.set_textarea(ta)
        kb.clear_flag(lv.obj.FLAG.HIDDEN)

    if code == lv.EVENT.DEFOCUSED:
        kb.set_textarea(None)
        kb.add_flag(lv.obj.FLAG.HIDDEN)

# Create a keyboard to use it with one of the text areas
kb = lv.keyboard(lv.scr_act())

# Create a text area. The keyboard will write here
ta = lv.textarea(lv.scr_act())
ta.set_width(200)
ta.align(lv.ALIGN.TOP_LEFT, 10, 10)
ta.add_event_cb(lambda e: ta_event_cb(e,kb), lv.EVENT.ALL, None)
ta.set_placeholder_text("Hello")

ta = lv.textarea(lv.scr_act())
ta.set_width(200)
ta.align(lv.ALIGN.TOP_RIGHT, -10, 10)
ta.add_event_cb(lambda e: ta_event_cb(e,kb), lv.EVENT.ALL, None)

kb.set_textarea(ta)

API¶

Typedefs

typedef uint8_t lv_keyboard_mode_t¶

Enums

Current keyboard mode.

Values:

enumerator LV_KEYBOARD_MODE_TEXT_LOWER¶

enumerator LV_KEYBOARD_MODE_TEXT_UPPER¶

enumerator LV_KEYBOARD_MODE_SPECIAL¶

enumerator LV_KEYBOARD_MODE_NUMBER¶

enumerator LV_KEYBOARD_MODE_USER_1¶

enumerator LV_KEYBOARD_MODE_USER_2¶

enumerator LV_KEYBOARD_MODE_USER_3¶

enumerator LV_KEYBOARD_MODE_USER_4¶

Functions

lv_obj_t *lv_keyboard_create(lv_obj_t *parent)¶

Create a Keyboard object

Parameters: parent -- pointer to an object, it will be the parent of the new keyboard
Returns: pointer to the created keyboard

void lv_keyboard_set_textarea(lv_obj_t *kb, lv_obj_t *ta)¶

Assign a Text Area to the Keyboard. The pressed characters will be put there.

Parameters

kb -- pointer to a Keyboard object
ta -- pointer to a Text Area object to write there

void lv_keyboard_set_mode(lv_obj_t *kb, lv_keyboard_mode_t mode)¶

Set a new a mode (text or number map)

Parameters

kb -- pointer to a Keyboard object
mode -- the mode from 'lv_keyboard_mode_t'

void lv_keyboard_set_popovers(lv_obj_t *kb, bool en)¶

Show the button title in a popover when pressed.

Parameters

kb -- pointer to a Keyboard object
en -- whether "popovers" mode is enabled

void lv_keyboard_set_map(lv_obj_t *kb, lv_keyboard_mode_t mode, const char *map[], const lv_btnmatrix_ctrl_t ctrl_map[])¶

Set a new map for the keyboard

Parameters

kb -- pointer to a Keyboard object
mode -- keyboard map to alter 'lv_keyboard_mode_t'
map -- pointer to a string array to describe the map. See 'lv_btnmatrix_set_map()' for more info.

lv_obj_t *lv_keyboard_get_textarea(const lv_obj_t *kb)¶

Assign a Text Area to the Keyboard. The pressed characters will be put there.

Parameters: kb -- pointer to a Keyboard object
Returns: pointer to the assigned Text Area object

lv_keyboard_mode_t lv_keyboard_get_mode(const lv_obj_t *kb)¶

Set a new a mode (text or number map)

Parameters: kb -- pointer to a Keyboard object
Returns: the current mode from 'lv_keyboard_mode_t'

bool lv_btnmatrix_get_popovers(const lv_obj_t *obj)¶

Tell whether "popovers" mode is enabled or not.

Parameters: kb -- pointer to a Keyboard object
Returns: true: "popovers" mode is enabled; false: disabled

static inline const char **lv_keyboard_get_map_array(const lv_obj_t *kb)¶

Get the current map of a keyboard

Parameters: kb -- pointer to a keyboard object
Returns: the current map

static inline uint16_t lv_keyboard_get_selected_btn(const lv_obj_t *obj)¶

Get the index of the lastly "activated" button by the user (pressed, released, focused etc) Useful in the event_cb to get the text of the button, check if hidden etc.

Parameters: obj -- pointer to button matrix object
Returns: index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)

static inline const char *lv_keyboard_get_btn_text(const lv_obj_t *obj, uint16_t btn_id)¶

Get the button's text

Parameters

obj -- pointer to button matrix object
btn_id -- the index a button not counting new line characters.

Returns

text of btn_index` button

void lv_keyboard_def_event_cb(lv_event_t *e)¶

Default keyboard event to add characters to the Text area and change the map. If a custom event_cb is added to the keyboard this function can be called from it to handle the button clicks

Parameters

kb -- pointer to a keyboard
event -- the triggering event

Variables

const lv_obj_class_t lv_keyboard_class¶

struct lv_keyboard_t¶

Public Members

lv_btnmatrix_t btnm¶

lv_obj_t *ta¶

lv_keyboard_mode_t mode¶

uint8_t popovers¶