文本输入控件¶

概述¶

文本输入控件提供文字编辑和虚拟键盘能力，适用于表单填写、搜索框、密码输入等嵌入式交互场景。包括文本输入框和虚拟键盘两个控件。

TextInput¶

文本输入框控件，支持光标移动、字符插入/删除、占位文字、文本变更回调和提交回调。

效果展示¶

API¶

函数	说明
`egui_view_textinput_init(self, core)`	初始化文本输入框
`egui_view_textinput_set_text(self, text)`	设置文本内容
`egui_view_textinput_get_text(self)`	获取文本内容
`egui_view_textinput_clear(self)`	清空文本
`egui_view_textinput_insert_char(self, c)`	在光标处插入字符
`egui_view_textinput_delete_char(self)`	删除光标前一个字符
`egui_view_textinput_delete_forward(self)`	删除光标后一个字符
`egui_view_textinput_set_cursor_pos(self, pos)`	设置光标位置
`egui_view_textinput_move_cursor_left(self)`	光标左移
`egui_view_textinput_move_cursor_right(self)`	光标右移
`egui_view_textinput_move_cursor_home(self)`	光标移到行首
`egui_view_textinput_move_cursor_end(self)`	光标移到行尾
`egui_view_textinput_set_font(self, font)`	设置字体
`egui_view_textinput_set_text_color(self, color, alpha)`	设置文字颜色
`egui_view_textinput_set_placeholder(self, placeholder)`	设置占位文字
`egui_view_textinput_set_placeholder_color(self, color, alpha)`	设置占位文字颜色
`egui_view_textinput_set_cursor_color(self, color)`	设置光标颜色
`egui_view_textinput_set_max_length(self, max_length)`	设置最大输入长度
`egui_view_textinput_set_on_text_changed(self, listener)`	设置文本变更回调
`egui_view_textinput_set_on_submit(self, listener)`	设置提交回调

回调函数原型¶

typedef void (*egui_view_textinput_on_text_changed_t)(egui_view_t *self, const char *text);
typedef void (*egui_view_textinput_on_submit_t)(egui_view_t *self, const char *text);

结构体字段¶

字段	类型	说明
`text`	`char[]`	文本缓冲区
`text_len`	`uint8_t`	当前文本长度
`cursor_pos`	`uint8_t`	光标位置
`max_length`	`uint8_t`	最大输入长度
`text_color`	`egui_color_t`	文字颜色
`placeholder_color`	`egui_color_t`	占位文字颜色
`cursor_color`	`egui_color_t`	光标颜色
`align_type`	`uint8_t`	文字对齐方式

配置选项¶

宏	说明
`EGUI_CONFIG_TEXTINPUT_MAX_LENGTH`	文本输入最大字符数

使用说明¶

TextInput 内置光标闪烁定时器，聚焦时自动显示闪烁光标
文本超出控件宽度时自动水平滚动，通过 scroll_offset_x 内部管理
on_text_changed 在每次字符插入或删除后触发
on_submit 在用户按下回车键（通过 Keyboard 的 Enter 键）时触发
通常与 Keyboard 控件配合使用，也可通过外部按键事件直接调用 insert_char / delete_char

代码示例¶

static egui_view_textinput_t input;

static void on_text_changed(egui_view_t *self, const char *text)
{
    EGUI_LOG_INF("Text: %s\n", text);
}

static void on_submit(egui_view_t *self, const char *text)
{
    EGUI_LOG_INF("Submit: %s\n", text);
}

void init_ui(egui_core_t *core)
{
    egui_view_textinput_init(EGUI_VIEW_OF(&input), core);
    egui_view_set_position(EGUI_VIEW_OF(&input), 10, 10);
    egui_view_set_size(EGUI_VIEW_OF(&input), 200, 30);
    egui_view_textinput_set_placeholder(EGUI_VIEW_OF(&input), "Enter text...");
    egui_view_textinput_set_max_length(EGUI_VIEW_OF(&input), 32);
    egui_view_textinput_set_on_text_changed(EGUI_VIEW_OF(&input),
        on_text_changed);
    egui_view_textinput_set_on_submit(EGUI_VIEW_OF(&input), on_submit);
    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&input));
}

Keyboard¶

虚拟键盘控件，继承自 Group，提供完整的 QWERTY 键盘布局，支持大小写切换和符号模式。与 TextInput 配合使用，自动处理键盘弹出时的视图避让。

效果展示¶

前置条件¶

Keyboard 需要同时启用按键和焦点支持：

#define EGUI_CONFIG_FUNCTION_SUPPORT_KEY   1
#define EGUI_CONFIG_FUNCTION_SUPPORT_FOCUS 1

API¶

函数	说明
`egui_view_keyboard_init(self, core)`	初始化键盘
`egui_view_keyboard_set_font(self, font)`	设置按键字体
`egui_view_keyboard_show(self, target_textinput)`	显示键盘并绑定目标输入框
`egui_view_keyboard_hide(self)`	隐藏键盘
`egui_view_keyboard_set_mode(self, mode)`	设置键盘模式

键盘模式常量¶

常量	值	说明
`EGUI_KEYBOARD_MODE_LOWERCASE`	0	小写字母
`EGUI_KEYBOARD_MODE_UPPERCASE`	1	大写字母
`EGUI_KEYBOARD_MODE_SYMBOLS`	2	符号

布局常量¶

常量	说明
`EGUI_KEYBOARD_ROW_COUNT`	键盘行数(4)
`EGUI_KEYBOARD_TOTAL_KEYS`	按键总数(31)
`EGUI_KEYBOARD_DEFAULT_WIDTH`	默认宽度(屏幕宽度)
`EGUI_KEYBOARD_DEFAULT_HEIGHT`	默认高度(128)

代码示例¶

static egui_view_textinput_t input;
static egui_view_keyboard_t keyboard;

void init_ui(egui_core_t *core)
{
    // 初始化输入框
    egui_view_textinput_init(EGUI_VIEW_OF(&input), core);
    egui_view_set_position(EGUI_VIEW_OF(&input), 10, 10);
    egui_view_set_size(EGUI_VIEW_OF(&input), 220, 30);
    egui_view_textinput_set_placeholder(EGUI_VIEW_OF(&input), "Tap to type");
    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&input));

    // 初始化键盘
    egui_view_keyboard_init(EGUI_VIEW_OF(&keyboard), core);
    egui_view_set_position(EGUI_VIEW_OF(&keyboard),
        0, EGUI_CONFIG_SCREEN_HEIGHT - EGUI_KEYBOARD_DEFAULT_HEIGHT);
    egui_core_add_user_root_view(core, EGUI_VIEW_OF(&keyboard));
}

void show_keyboard(void)
{
    egui_view_keyboard_show(EGUI_VIEW_OF(&keyboard), EGUI_VIEW_OF(&input));
}

void hide_keyboard(void)
{
    egui_view_keyboard_hide(EGUI_VIEW_OF(&keyboard));
}

特殊按键索引¶

常量	值	说明
`EGUI_KEYBOARD_KEY_IDX_SHIFT`	19	Shift 键
`EGUI_KEYBOARD_KEY_IDX_BACKSPACE`	27	退格键
`EGUI_KEYBOARD_KEY_IDX_MODE`	28	模式切换键
`EGUI_KEYBOARD_KEY_IDX_SPACE`	29	空格键
`EGUI_KEYBOARD_KEY_IDX_ENTER`	30	回车键

使用说明¶

Keyboard 在调用 show() 时自动绑定目标 TextInput，按键输入直接写入目标输入框
键盘弹出时会自动调整被遮挡的视图位置（键盘避让），隐藏时恢复原位
Shift 键切换大小写，Mode 键在字母和符号之间切换
键盘宽度默认为屏幕宽度 EGUI_CONFIG_SCREEN_WIDTH，适配不同分辨率需调整按键宽度常量
键盘内部使用 LinearLayout 排列按键行，每行按键数量固定