lvgl9 消息框控件Message(lv_message)使用指南

前言

在图形用户界面中，消息框（Message Box）是一种常见的弹出式对话框，用于显示重要信息或与用户进行交互。LittlevGL 提供了 lv_msgbox 控件，它可以轻松实现此功能，包括标题、文本、关闭按钮以及操作按钮，支持模态（阻止屏幕其他部分点击）和非模态模式。通过消息框，开发者可以在不破坏当前界面的情况下提供关键信息或收集用户的反馈。

1. 控件概述

lv_msgbox 是一种弹出式控件，由以下元素组成：

• 背景容器：显示消息框的边界和背景。
• 标题：用于显示消息框的标题。
• 关闭按钮（可选）：用于快速关闭消息框。
• 文本：消息内容，可自动换行。
• 操作按钮（可选）：用于接收用户输入或操作。

此外，消息框可以根据需要设置为模态或非模态。模态消息框会阻止用户与其他屏幕元素交互，而非模态消息框允许其他控件正常工作。

2. 控件的样式和组成部分

消息框本质上是由其他控件组合而成，因此可以通过这些控件的文档进一步了解样式设置：

• 背景：参考 lv_obj.h。
• 关闭按钮：参考 lv_button.h。
• 标题与文本：参考 lv_label.h。
• 按钮矩阵：参考 lv_buttonmatrix.h。

这些部分可以单独获取，以便精细地调整其样式和功能。

3. 使用场景

消息框控件适用于以下常见场景：

• 信息提示：用于向用户展示重要信息，例如通知、警告或错误消息。
• 用户确认：提供多个按钮选项，收集用户的选择，例如“确定”或“取消”。
• 模态交互：阻止用户与界面其他部分交互，直到做出选择或关闭消息框。
• 临时输入框：可以包含按钮供用户快速操作，例如提交或关闭。

4. 创建消息框

基本用法

通过 lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn) 创建消息框。参数说明如下：

• parent：消息框的父控件。如果为 NULL，消息框会以模态方式显示。
• title：消息框的标题字符串。
• txt：消息框显示的文本内容。
• btn_txts[]：一个包含按钮文本的字符串数组。例如，const char *btn_txts[] = {"Ok", "Cancel", NULL};。
• add_close_btn：布尔值，是否添加关闭按钮。

示例代码：

const char *btn_txts[] = {"Ok", "Cancel", NULL};
lv_obj_t *msgbox = lv_msgbox_create(NULL, "Title", "This is a message", btn_txts, true);

设置模态模式

当 parent 参数为 NULL 时，消息框将以模态模式显示，阻止用户点击界面的其他部分。否则，消息框为非模态。

5. 获取消息框组件

消息框的子元素可以单独获取以便进一步操作，使用以下函数：

• 获取标题对象：lv_msgbox_get_title(msgbox)
• 获取关闭按钮对象：lv_msgbox_get_close_btn(msgbox)
• 获取文本对象：lv_msgbox_get_text(msgbox)
• 获取按钮矩阵对象：lv_msgbox_get_btns(msgbox)

示例代码：

lv_obj_t *title = lv_msgbox_get_title(msgbox);  // 获取标题对象
lv_obj_t *text = lv_msgbox_get_text(msgbox);    // 获取文本对象

6. 关闭消息框

通过 lv_msgbox_close(msgbox) 可以关闭并删除消息框。

lv_msgbox_close(msgbox);  // 关闭消息框

7. 事件处理

消息框的按钮触发 LV_EVENT_VALUE_CHANGED 事件。当按钮被点击时，可以通过以下函数获取被点击的按钮索引和文本：

• 获取被点击按钮的索引：lv_msgbox_get_active_button(msgbox)
• 获取被点击按钮的文本：lv_msgbox_get_active_button_text(msgbox)

示例代码：

void event_handler(lv_event_t *e) {
    lv_obj_t *msgbox = lv_event_get_current_target(e);
    const char *btn_text = lv_msgbox_get_active_button_text(msgbox);
    printf("Button clicked: %s\n", btn_text);
}

8. 键盘支持

消息框支持对关闭按钮和按钮矩阵的键盘交互。如果需要，可以将它们手动添加到输入设备组中，以响应键盘事件。

9. 示例代码

以下是一个简单的消息框示例：

void event_handler(lv_event_t *e) {
    lv_obj_t *msgbox = lv_event_get_current_target(e);
    const char *btn_text = lv_msgbox_get_active_button_text(msgbox);
    printf("Button clicked: %s\n", btn_text);
    lv_msgbox_close(msgbox);  // 点击后关闭消息框
}

void create_msgbox() {
    const char *btn_txts[] = {"Yes", "No", "Cancel", NULL};
    lv_obj_t *msgbox = lv_msgbox_create(NULL, "Confirm", "Are you sure?", btn_txts, true);
    lv_obj_center(msgbox);
    lv_obj_add_event_cb(msgbox, event_handler, LV_EVENT_VALUE_CHANGED, NULL);
}

此示例创建了一个模态消息框，用户点击任意按钮后会输出对应的按钮文本，并关闭消息框。

总结

lv_msgbox 是一个功能强大且易于使用的控件，适合在界面中创建弹出式对话框。它的模态功能可以强制用户完成操作或关闭消息框后再继续交互，同时它也支持丰富的样式和事件处理，能够满足多种需求。从简单的通知到复杂的用户输入交互，lv_msgbox 都能够提供强大的支持，是嵌入式 GUI 开发中不可或缺的工具。