04. 标签部件

一、LVGL的标签部件

  在 LVGL 中，标签部件 常用于文本显示，例如标题、提示文本等。标签部件由三个部分组成：主体背景（LV_PART_MAIN）、滚动条（LV_PART_SCROLLBAR）和 所选文本（LV_PART_SELECTED）。

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

lv_obj_t * lv_label_create(lv_obj_t * parent);                                  // 创建标签部件

void lv_label_set_text(lv_obj_t * obj, const char * text);                      // 设置标签的新文本
void lv_label_set_text_fmt(lv_obj_t * obj, const char * fmt, ...);              // 设置标签的新格式的文本
void lv_label_set_text_static(lv_obj_t * obj, const char * text);               // 设置一个静态文本
char * lv_label_get_text(const lv_obj_t * obj);                                 // 获取标签文本

void lv_label_set_long_mode(void);                                              // 使用更长的文本然后设置部件大小来设置标签
void lv_label_set_long_mode(lv_obj_t * obj, lv_label_long_mode_t long_mode);    // 使用更长的文本然后设置部件大小来设置标签

void lv_label_set_text_selection_start(lv_obj_t * obj, uint32_t index);         // 设置选择开始索引
uint32_t lv_label_get_text_selection_start(const lv_obj_t * obj);               // 获取选择开始索引

void lv_label_set_text_selection_end(lv_obj_t * obj, uint32_t index);           // 设置选择结束索引
uint32_t lv_label_get_text_selection_end(const lv_obj_t * obj);                 // 获取选择结束索引

void lv_label_ins_text(lv_obj_t * obj, uint32_t pos, const char * txt);         // 在标签上插入文本，标签文本不能是静态的
void lv_label_cut_text(lv_obj_t * obj, uint32_t pos, uint32_t cnt);             // 从标签中删除字符，标签文本不能是静态的

void lv_label_get_letter_pos(const lv_obj_t * obj, uint32_t char_id, lv_point_t * pos); // 获取字母的相对 x 和 y 坐标
uint32_t lv_label_get_letter_on(const lv_obj_t * obj, lv_point_t * pos_in, bool bidi);  // 获取标签相对点上的字母索引
bool lv_label_is_char_under_pos(const lv_obj_t * obj, lv_point_t * pos);                // 检查是否在一个点下绘制了一个字符

  我们可以使用 lv_label_create() 函数 创建标签部件，该函数原型如下所示：

/**
 * @brief 创建标签部件
 * 
 * @param parent 指向父部件的指针
 * @return lv_obj_t* 指向标签部件的指针
 */
lv_obj_t * lv_label_create(lv_obj_t * parent);

  在创建标签部件后，我们可以使用 lv_label_set_text() 函数 设置标签文本。如果要 设置格式化文本，我们可以使用 lv_label_set_text_fmt() 函数，如果要 设置为长文本模式，我们可以使用 lv_label_set_long_mode() 函数。

/**
 * @brief 设置标签的新文本
 * 
 * @param obj 指向标签部件的指针
 * @param text 文本字符串
 */
void lv_label_set_text(lv_obj_t * obj, const char * text);

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

/**
 * @brief 设置一个静态文本
 * 
 * @param obj 指向标签部件的指针
 * @param text 文本字符串
 */
void lv_label_set_text_static(lv_obj_t * obj, const char * text);

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

/**
 * @brief 设置标签的新格式的文本
 * 
 * @param obj 指向标签部件的指针
 * @param fmt 指定要显示的格式化字符串
 * @param ... 格式化字符串参数列表
 */
void lv_label_set_text_fmt(lv_obj_t * obj, const char * fmt, ...);

  该函数与 C 语言的 sprintf() 输出函数类似，都可以设置“式样化字符串”和“参数表”。

/**
 * @brief 设置字体样式
 * 
 * @param obj 指向部件的指针
 * @param value 字体的大小
 * @param selector 选择应用样式的特定部分
 */
void lv_obj_set_style_text_font(lv_obj_t * obj, const lv_font_t * value, lv_style_selector_t selector);

  当我们调用 lv_obj_set_style_text_font() 函数设置标签字体大小时，我们需要将 LVGL 提供的对应的宏置一，才能使用对应的字体。

/**
 * @brief 设置长文本模式
 * 
 * @param obj 指向标签部件的指针
 * @param long_mode 长文本模式
 */
void lv_label_set_long_mode(lv_obj_t * obj, lv_label_long_mode_t long_mode);

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

enum _lv_label_long_mode_t {
    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,             // 直接裁剪标签部件外面的文本
};

文本只会往一个方向滚动，水平方向具有更高的优先级。

二、实验例程

#include "lvgl.h"
#include "lv_port_disp_template.h"
#include "lv_port_indev_template.h"

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 *label = lv_label_create(lv_scr_act());                                // 创建标签部件
    lv_label_set_text(label, "Hello Shana, my name is Sakura, nice to meet you");   // 设置标签部件的文本

    lv_obj_set_style_bg_color(label, lv_color_hex(0xFF0000), LV_STATE_DEFAULT);     // 设置标签部件的背景颜色
    lv_obj_set_style_bg_opa(label, 100, LV_STATE_DEFAULT);                          // 设置标签部件的背景透明度

    lv_obj_set_style_text_color(label, lv_color_hex(0x0000FF), LV_STATE_DEFAULT);   // 设置标签部件的字体颜色

    lv_obj_set_style_text_font(label, &lv_font_montserrat_30, LV_STATE_DEFAULT);    // 设置标签部件的字体

    lv_obj_set_size(label, 100, 60);                                                // 设置标签部件的大小

    lv_label_set_long_mode(label, LV_LABEL_LONG_SCROLL_CIRCULAR);                   // 设置标签部件模式为长文本模式


    while (1)
    {
        lv_timer_handler();
        Delay_ms(5);
    }
  
    return 0;
}