第十四章 标签部件(lv_label)

       在LVGL中，标签部件常用于文本显示，例如标题、提示文本等。

       本章节将分为以下几个小节：

       14.1 标签部件的组成

       14.2 标签部件的相关知识

       14.3 标签部件的API函数

       14.4 标签部件的实验

        14.1 标签部件的组成

       标签部件由三个部分组成：主体背景、滚动条和所选文本，示意图如下：

图14.1.1 标签部件组成部分

       各组成部分的相关枚举如下所示：

       ① 主体背景LV_PART_MAIN；

       ② 滚动条LV_PART_SCROLLBAR；

       ③ 所选文本LV_PART_SELECTED。

       关于部件样式设置的内容，请大家参考6.4.4章节。

        14.2 标签部件的相关知识

       14.2.1文本设置

       设置标签部件文本的方法有三种：

       第一种：调用lv_label_set_text函数

       该函数是最常用的标签文本设置函数，它存储文本的内存由动态内存分配的。

       第二种：调用lv_label_set_text_fmt函数

       该函数与C语言的sprintf输出函数类似，都可以设置“式样化字符串”和“参数表”，示例代码如下：

lv_label_set_text_fmt(label, "Value: %d", 15);

        第三种：调用label_set_text_static函数

       该函数可以设置静态文本，该文本不存储在动态内存中，而是直接使用指定的缓冲区，此时，如果使用数组设置文本，则该数组不能是局部变量。

       14.2.2 换行符设置

       如果用户想把文本分为两段进行显示，则可在内容的末尾添加“\n”，其后续的文本将会换行。 

       接下来，我们以简单示例来理解标签换行的设置，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* lv_label1 = lv_label_create(lv_scr_act());
    lv_label_set_text(lv_label1, "ALIENTEK \nLVGL \nDemo text");
 
    lv_obj_t* lv_label2 = lv_label_create(lv_scr_act());
lv_obj_align_to(lv_label2, lv_label1,LV_ALIGN_OUT_BOTTOM_MID,0,0); 
/* 设置标签文本及偏移 */
    lv_label_set_text_fmt(lv_label2, "Label value %d", 20);
}

       在上述源码中，我们创建了两个标签部件，label1部件调用lv_label_set_text函数设置文本，并使用“\n”进行换行，而label2部件调用lv_label_set_text_fmt函数设置文本。示例代码可以在PC模拟器中运行，效果图如下所示：

图14.2.2.1 标签部件文本换行

       14.2.3 文本长模式

       默认情况下，标签部件的宽度和高度都会根据文本的大小来动态变化。如果用户固定了标签部件的大小，并且文本的长度超过了部件的长度，则可以使用以下几个长文本模式来选择文本展现的形式：

       ① LV_LABEL_LONG_WRAP（默认）：如果标签部件的高度是LV_SIZE_CONTENT，则该部件高度将被扩展，否则文本将被剪切。

       ② LV_LABEL_LONG_DOT：将标签文本右下角的最后3个字符替换为点。

       ③ LV_LABEL_LONG_SCROLL：来回滚动。如果文本比标签部件宽，则往水平方向滚动。如果文本比标签部件高，则往垂直方向滚动。注意：文本只会往一个方向滚动，水平方向具有更高的优先级。

       ④ LV_LABEL_LONG_SCROLL_CIRCULAR：循环滚动。如果文本比标签部件宽，则往水平方向滚动。如果文本比标签部件高，则往垂直方向滚动。注意：文本只会往一个方向滚动，水平方向具有更高的优先级。

       ⑤  LV_LABEL_LONG_CLIP：直接裁剪标签部件外面的文本。

       用户需要设置长文本模式，可调用lv_label_set_long_mode函数。

       14.2.4 文本着色

       用户需要让标签文本着色，可以调用lv_label_set_recolor函数。接下来，我们以简单示例来理解标签文本着色，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* lv_label1 = lv_label_create(lv_scr_act());
lv_label_set_text(lv_label1, "ALIENTEK #ff0000 LVGL# Demo text");
/* 使能重新着色 */
    lv_label_set_recolor(lv_label1,true);
}

       在上述源码中，我们创建了一个标签部件，然后设置文本中的“LVGL”字符串颜色为红色（ff00000），最后使能文本重新着色功能。注意：用户需要设置标签文本着色，必须按以下格式设置文本：#颜色 文本#。示例代码可以在PC模拟器中运行，效果图如下所示：

图14.2.4.1设置文本颜色

        14.3 标签部件的API函数

       LVGL官方提供了一些与标签部件相关API，如下表所示：

表14.3.1 标签部件相关的API函数

       接下来，我们介绍LVGL标签部件常用的API函数：

       1. lv_label_create函数

       创建标签部件，该函数原型如下所示：

lv_obj_t *lv_label_create(lv_obj_t *parent);

       该函数的形参，如表14.3.2所示：

表14.3.2 lv_label_create函数形参描述

       返回值：无

       2. lv_label_set_text函数

       设置文本（动态），该函数原型如下所示：

void lv_label_set_text(lv_obj_t *obj, const char *text);

       该函数的形参，如表14.3.3所示：

表14.3.3 lv_label_set_text函数形参描述

       返回值：无

       3. lv_label_set_text_fmt函数

       设置格式化文本，该函数原型如下所示：

void lv_label_set_text_fmt(lv_obj_t *obj, const char *fmt, ...);

       该函数的形参，如表14.3.4所示：

表14.3.4 lv_label_set_text_fmt函数形参描述

       返回值：无

       4. lv_label_set_long_mode函数

       设置长文本模式，该函数原型如下所示：

void lv_label_set_long_mode(lv_obj_t *obj, lv_label_long_mode_t long_mode);

       该函数的形参，如表14.3.5所示：

表14.3.5 lv_label_set_long_mode函数形参描述

       返回值：无

       5. lv_label_set_recolor函数

       设置文本重新着色，该函数原型如下所示：

void lv_label_set_recolor(lv_obj_t *obj, bool en);

       该函数的形参，如表14.3.6所示：

表14.3.6 lv_label_set_recolor函数形参描述

       返回值：无

        14.4 标签部件的实验

       14.4.1 硬件设计

       1. 例程功能

       本实验主要测试标签部件API函数的使用，实验现象：开机后，屏幕上显示一行滚动的文本，其同时带有重着色的效果。与此同时，LED0闪烁，提示系统正在运行。

       该实验的完整源码，请参考《LVGL例程11 lv_label(标签)》例程，路径：A盘→4，程序源码 →3，扩展例程 →3，LVGL例程。

       14.4.2 软件设计

       14.4.2.1 程序流程图

       本实验的程序流程图，如下图14.4.2.1.1所示：

图14.4.2.1.1 标签部件实验流程图

       14.4.2.2 程序解析

       关于LVGL的用户代码，我们都是在lv_mainstart.c文件中编写的，本实验的源码如下所示：

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_label();
}
 
/**************************** 第一部分 结束 ****************************/
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  标签示例
 * @param  无
 * @return 无
 */
static void lv_example_label(void)
{
/* 定义并创建标签 */
lv_obj_t* label = lv_label_create(lv_scr_act());  
/* 设置标签文本 */
lv_label_set_text(label, "It is a circularly #ff0000 scrolling text.#"); 
/* 设置标签文本字体 */
lv_obj_set_style_text_font(label, &lv_font_montserrat_22, LV_PART_MAIN); 
/* 启用标签文本重新着色 */
lv_label_set_recolor(label, true); 
/* 设置标签宽度 */
lv_obj_set_width(label, 210);   
/* 设置标签长模式：循环滚动 */
lv_label_set_long_mode(label, LV_LABEL_LONG_SCROLL_CIRCULAR);  
/* 设置标签位置 */
    lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); 
}
/**************************** 第二部分 结束 ****************************/

       上述源码可分为以下两个部分：

       ① lv_mainstart接口函数。在该函数中，我们调用了标签部件相关的示例函数；

       ② 我们在lv_example_label函数中设置标签部件的文本重新着色、长文本模式。

       14.4 . 3 下载验证

       把工程编译并下载到我们的开发板中， 运行效果如图14.4.3.1所示：

图14.4.3.1 标签部件实验