第十五章 线条部件(lv_line)

       线条部件由多个点连接而成，它可用于修饰界面或者展示数据。

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

       15.1 线部件的组成

       15.2 线部件的相关知识

       15.3 线部件的API函数

       15.4 线部件的实验

        15.1 线条部件的组成

       线条部件只有一个组成部分：主体LV_PART_MAIN。关于部件样式设置的内容，请大家参考6.4.4章节。

        15.2 线条部件的相关知识

       15.2.1 设置连接点

       线条是由多个点连接而成的对象，用户可以使用lv_point_t类型的数组存储这些坐标点，并调用lv_line_set_points函数，把这些坐标点传递给线条部件，它将会把这些点连接起来，最终绘制成线条。

       接下来，我们以简单示例来理解线条连接点的设置，示例代码如下所示：

void lv_mainstart(void)
{
    /* 为直线的点创建一个数组 */
static lv_point_t line_points[] = { {5, 5}, {70, 70}, {120, 10}, 
{180, 60}, {240, 10} };
    lv_obj_t* line1;                       
    line1 = lv_line_create(lv_scr_act());       /* 创建line部件 */
    lv_line_set_points(line1, line_points, 5);  /* 设置线部件的点数组 */
    lv_obj_center(line1);                       /* 居中 */
}

       在上述源码中，我们先创建连接点相关的数组，然后创建一个线条部件，最后将点数组传入到线条部件中，其将会把这些点连接起来。示例代码可以在PC模拟器中运行，效果图如下所示：

图15.2.1.1 设置线条连接点

       上图中，因为线条部件被居中对齐，所以坐标原点在该部件居中后的左上方，如下图所示：

图15.2.1.2坐标点示意图

       15.2.2 自适应大小

       默认情况下，线条部件的宽度和高度都是LV_SIZE_CONTENT，这意味着它将自动设置自身的大小，以适应所有的点。如果用户设置了线条部件的大小，则超出的部分可能不可见。

       15.2.3 倒Y 操作

       倒Y操作指的是将线条部件的参考原点设置到左下角，其最终效果相当于将线条沿Y轴方向镜像翻转。用户需要进行倒Y操作，可调用lv_line_set_y_invert函数，效果图如下所示：

图15.2.3.1 设置线条部件倒Y

        15.3 线条部件的API函数

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

表15.3.1.1 线条部件相关的API函数

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

       1. lv_line_create函数

       创建线条部件，该函数原型如下所示：

lv_obj_t *lv_line_create(lv_obj_t *parent);

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

表15.3.2 lv_line_create函数形参描述

       返回值：无。

       2. lv_line_set_points函数

       设置一个点数组，该函数原型如下所示：

void lv_line_set_points(lv_obj_t *obj, const lv_point_t points[], 
uint16_t point_num);

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

表15.3.3 lv_line_set_points函数形参描述

       返回值：无。

       3. lv_line_set_y_invert函数

       启用或禁用Y坐标反转，该函数原型如下所示：

void lv_line_set_y_invert(lv_obj_t *obj, bool en);

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

表15.3.4 lv_line_set_y_invert函数形参描述

       返回值：无。

       4. lv_line_get_y_invert函数

       获取Y轴反转属性，该函数原型如下所示：

bool lv_line_get_y_invert(const lv_obj_t *obj);

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

表15.3.5 lv_line_get_y_invert函数形参描述

       返回值：true:开启，false:关闭。

        15.4 线条部件的实验

       15.4.1 硬件设计

       15.4.1.1 硬件设计

       本实验主要测试线条部件API函数的使用，实验现象：开机后，屏幕上显示一个标题和一条正弦波曲线。与此同时，LED0闪烁，提示系统正在运行。

       该实验的完整源码，请参考《LVGL例程12 lv_line(线条)》例程，路径：A盘→4，程序源码 →3，扩展例程 →3，LVGL例程。

       15.4.2 软件设计

       15.4.2.1 程序流程图

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

图15.4.2.1.1 线条部件实验流程图

       15.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_line();         /* 正弦波实例 */
}
/**************************** 第一部分 结束 ****************************/
/**************************** 第二部分 开始 ****************************/
/**
 * @brief       产生正弦波坐标点
 * @param       maxval : 峰值
 * @param       samples: 坐标点的个数
 * @retval      无
 */
static void create_sin_buf(uint16_t maxval, uint16_t samples)
{
    uint16_t i;
    float y = 0;
    /*
     * 正弦波最小正周期为2π，约等于2 * 3.1415926
     * 曲线上相邻的两个点在x轴上的间隔 = 2 * 3.1415926 / 采样点数量
     */
    float inc = (2 * 3.1415926) / samples;  /* 计算相邻两个点的x轴间隔 */
    for (i = 0; i < samples; i++)           /* 连续产生samples个点 */
    {
        /*
         * 正弦波函数解析式：y = Asin(wx + φ）+ b
         * 计算每个点的y值，将峰值放大maxval倍，并将曲线向上偏移maxval到正数区域
         */
        y = maxval * sin(inc * i) + maxval;
        sin_line_points[i].x = i;            /* 存入x轴坐标 */
        sin_line_points[i].y = y;            /* 存入y轴坐标 */
    }
}
 
/**
 * @brief  正弦波实例
 * @param  无
 * @return 无
 */
static void lv_example_line(void)
{
    /* 标题 */
    lv_obj_t *label = lv_label_create(lv_scr_act());        /* 创建标签 */
    lv_label_set_text(label, "Line");                       /* 设置文本内容 */
    lv_obj_set_style_text_font(label, &lv_font_montserrat_22, 0); /* 设置字体 */
lv_obj_align(label, LV_ALIGN_TOP_LEFT, scr_act_width() / 20, 
scr_act_height()/16);                      /* 设置位置 */
 
    /* 直线（用作下划线）*/
    lv_obj_t *straigh_line = lv_line_create(lv_scr_act());  /* 创建线条 */
lv_line_set_points(straigh_line, straigh_line_points, 2); /* 设置线条坐标点 */
/* 设置位置 */
    lv_obj_align_to(straigh_line, label, LV_ALIGN_OUT_BOTTOM_LEFT, 0, 0);   
 
    /* 正弦波 */
    lv_obj_t *sin_line = lv_line_create(lv_scr_act());      /* 创建线条 */
create_sin_buf(scr_act_height()/4, SIN_POINTS_NUM);    /* 产生正弦波坐标点 */
/* 设置线条坐标点 */
    lv_line_set_points(sin_line, sin_line_points, SIN_POINTS_NUM);
    lv_obj_center(sin_line);                                 /* 设置位置 */
    lv_obj_set_style_line_width(sin_line, 8, LV_PART_MAIN);  /* 设置线的宽度 */
lv_obj_set_style_line_color(sin_line, lv_palette_main(LV_PALETTE_BLUE), 
LV_PART_MAIN);                /* 设置线的颜色 */
/* 设置线条圆角 */
    lv_obj_set_style_line_rounded(sin_line, true, LV_PART_MAIN); 
}
/**************************** 第二部分 结束 ****************************/

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

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

       ② 正弦波曲线的实现。我们创建标题标签以及下划线，然后创建正弦波相关的线条部件，并将create_sin_buf函数所产生的正弦波序列数组设置为其坐标点，从而得到一条正弦波曲线。

       15.4.3 下载验证

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

图15.4.3.1 线条部件实验