列表 (List)

列表控件 (List) 作为容器可以在水平或垂直方向上添加任意数量的表格（动态创建，节省内存和 CPU 开销），每个表格都可以添加其他的控件，如文本控件，图片控件等等，用户可以通过上下左右滑动来访问添加到列表控件上的其他控件。

https://foruda.gitee.com/images/1745465574757113257/5e8ee605_10737458.gif — Vertical Classic List

用法

创建列表控件

使用 gui_list_create() 函数来创建一个列表控件（可选滚动条），列表控件的下一级只能是表格控件，在 note_design 中根据表格控件的 index 进行对应的子控件设计，实现动态创建表格控件。列表控件的总长度由添加的表格数量、表格长度以及表格间隔决定，当添加的表格越多时，其长度也越大。

设置列表控件的样式

使用 gui_list_set_style() 函数可以设置列表控件的样式，默认为 LIST_CLASSIC, 具体有以下几种：

typedef enum
{
    LIST_CLASSIC = 0, ///< Classic list.
    LIST_CIRCLE,           ///< Circle list.
    LIST_ZOOM,             ///< Zoom center list.
    LIST_CARD,             ///< Stack like card.
    LIST_FADE,             ///< Fade in.
    LIST_FAN,              ///< Rotate like fan.
    LIST_HELIX,            ///< Rotate like helix.
    LIST_CURL,             ///< Rotate curly.
} LIST_STYLE;

设置列表控件的减速系数

使用 gui_list_set_factor() 函数设置列表控件的减速系数。

设置列表控件的偏移位置

使用 gui_list_set_offset() 函数设置列表控件的偏移位置。

设置列表控件滚动条颜色

使用 gui_list_set_bar_color() 函数设置列表控件的滚动条颜色。

设置列表控件表格数量

使用 gui_list_set_note_num() 函数设置列表控件的表格数量。

设置卡片样式堆叠位置

使用 gui_list_set_card_stack_location() 函数设置卡片样式堆叠位置。

设置列表控件超出区域范围

使用 gui_list_set_out_scope() 函数设置列表控件超出区域范围。

设置列表控件自动对齐

使用 gui_list_set_auto_align() 函数设置列表控件自动对齐。

设置列表控件惯性滚动

使用 gui_list_set_inertia() 函数设置列表控件惯性滚动。

设置列表循环滚动

使用 gui_list_enable_loop() 函数设置列表控件循环滚动，当列表总长度大于列表宽度或高度时生效。

示例

#include "guidef.h"
#include "string.h"
#include "stdio.h"
#include "stdlib.h"
#include "gui_server.h"
#include "gui_components_init.h"
#include "gui_canvas_rect.h"
#include "gui_list.h"

/* Use the following macro to checkout the different style lists */
// #define RUN_VERTICAL_CIRCLE_STYLE
// #define RUN_VERTICAL_CARD_STYLE
// #define RUN_HORIZONTAL_ZOOM_STYLE
// #define RUN_VERTICAL_FAN_STYLE
#define RUN_VERTICAL_HELIX_STYLE
// #define RUN_VERTICAL_CURL_STYLE
// #define RUN_VERTICAL_CLASSIC_STYLE
// #define RUN_VERTICAL_FADE_STYLE

#define NOTE_NUM 20

int length = 100;

static void note_design(gui_obj_t *obj, void *p)
{
    GUI_UNUSED(p);
    gui_color_t color[] =
    {
        APP_COLOR_WHITE_OPACITY,
        APP_COLOR_GRAY,
        APP_COLOR_SILVER_OPACITY(150),
        APP_COLOR_WHITE,
        APP_COLOR_GRAY_OPACITY(150),
        APP_COLOR_RED,
        APP_COLOR_GREEN,
        APP_COLOR_BLUE,
    };
    uint16_t index = ((gui_list_note_t *)obj)->index % (sizeof(color) / sizeof(gui_color_t));
#ifdef RUN_VERTICAL_CIRCLE_STYLE
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 0, 0, 480, 100, color[index]);
#endif

#ifdef RUN_HORIZONTAL_ZOOM_STYLE
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 0, 0, 100, 480, color[index]);
#endif

#ifdef RUN_VERTICAL_CARD_STYLE
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 50, 0, 380, 150, color[index]);
#endif

#ifdef RUN_VERTICAL_FAN_STYLE
    gui_color_t color2[] =
    {
        APP_COLOR_SILVER_OPACITY(150),
        APP_COLOR_WHITE_OPACITY,
    };
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 50, 0, 380, 100, color2[index % 2]);
#endif

#ifdef RUN_VERTICAL_HELIX_STYLE
    gui_color_t color2[] =
    {
        APP_COLOR_SILVER_OPACITY(150),
        APP_COLOR_WHITE_OPACITY,
    };
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 50, 0, 380, 100, color2[index % 2]);
#endif

#ifdef RUN_VERTICAL_CURL_STYLE
    gui_color_t color2[] =
    {
        APP_COLOR_SILVER_OPACITY(150),
        APP_COLOR_WHITE_OPACITY,
    };
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 0, 0, 0, 100, color2[index % 2]);
#endif

#ifdef RUN_VERTICAL_CLASSIC_STYLE
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 0, 0, 480, 480, color[index]);
#endif

#ifdef RUN_VERTICAL_FADE_STYLE
    gui_canvas_rect_t *canvas = gui_canvas_rect_create(obj, "note", 0, 0, 480, 480, color[index]);
#endif
    GUI_UNUSED(canvas);
}

static int app_init(void)
{
    uint16_t space = 0;

    /* VERTICAL CIRCLE STYLE */
#ifdef RUN_VERTICAL_CIRCLE_STYLE

    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL, false);
    gui_list_set_note_num(list, NOTE_NUM);
    gui_list_set_style(list, LIST_CIRCLE);
    gui_list_set_out_scope(list, 100);
    return 0;
#endif


    /* VERTICAL CARD STYLE */
#ifdef RUN_VERTICAL_CARD_STYLE
    int length = 150;
    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL,
                                       false);
    gui_list_set_style(list, LIST_CARD); //if LIST_CARD style, must set style before set note num
    gui_list_set_note_num(list, NOTE_NUM);
    gui_list_set_card_stack_location(list, 20);
    return 0;
#endif

    /* HORIZONTAL ZOOM STYLE */
#ifdef RUN_HORIZONTAL_ZOOM_STYLE

    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space,
                                       HORIZONTAL, note_design, NULL, false);
    gui_list_set_style(list, LIST_ZOOM);
    gui_list_set_note_num(list, NOTE_NUM);
    return 0;
#endif

    /* VERTICAL FAN STYLE */
#ifdef RUN_VERTICAL_FAN_STYLE

    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL, false);
    gui_list_set_note_num(list, NOTE_NUM);
    gui_list_set_style(list, LIST_FAN);
    return 0;
#endif

    /* VERTICAL HELIX STYLE */
#ifdef RUN_VERTICAL_HELIX_STYLE
    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL, false);
    gui_list_set_note_num(list, NOTE_NUM);
    gui_list_set_style(list, LIST_HELIX);
    gui_list_set_auto_align(list, true);
    gui_list_enable_loop(list, true);
    return 0;
#endif

    /* VERTICAL CURL STYLE */
#ifdef RUN_VERTICAL_CURL_STYLE
    space = 0;

    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL, false);
    gui_list_set_note_num(list, NOTE_NUM);
    gui_list_set_style(list, LIST_CURL);
    return 0;
#endif

    /* VERTICAL CLASSIC STYLE */
#ifdef RUN_VERTICAL_CLASSIC_STYLE
    int length = 480;
    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL,
                                       false);
    gui_list_set_style(list, LIST_CLASSIC); //if LIST_CARD style, must set style before set note num
    gui_list_set_note_num(list, 10);
    gui_list_set_auto_align(list, true);
    gui_list_set_offset(list, -length * 5);
    gui_list_set_inertia(list, false);
    return 0;
#endif

    /* VERTICAL FADE STYLE */
#ifdef RUN_VERTICAL_FADE_STYLE
    int length = 480;
    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 0, length, space, VERTICAL,
                                       note_design, NULL,
                                       false);
    gui_list_set_style(list, LIST_FADE);
    gui_list_set_note_num(list, 10);
    gui_list_set_auto_align(list, true);
    gui_list_set_inertia(list, false);
    gui_list_set_out_scope(list, 480 / 2);
    gui_list_set_offset(list, -length * 5);
    return 0;
#endif
}

GUI_INIT_APP_EXPORT(app_init);

Vertical Circle Style	Vertical Card Style	Horizontal Zoom Style
Vertical Fan Style	Vertical Helix Style	Vertical Curl Style

API

Defines

GUI_MAX_SPEED 50

GUI_MIN_SPEED 10

LIST_TAB_ANIMATE_MAX 15

LIST_BAR_WIDTH 5

Enums

enum LIST_STYLE

Values:

enumerator LIST_CLASSIC: Classic list.

enumerator LIST_CIRCLE: Circle list.

enumerator LIST_ZOOM: Zoom center list.

enumerator LIST_CARD: Stack like card.

enumerator LIST_FADE: Fade in.

enumerator LIST_FAN: Rotate like fan.

enumerator LIST_HELIX: Rotate like helix.

enumerator LIST_CURL: Rotate curly.

enum LIST_DIR

Values:

enumerator VERTICAL

enumerator HORIZONTAL

Functions

gui_list_t *gui_list_create(void *parent, const char *name, int16_t x, int16_t y, int16_t w, int16_t h, uint16_t note_length, uint8_t space, LIST_DIR dir, void (*note_design)(gui_obj_t *obj, void *param), void *design_param, bool create_bar)

Create a list widget.

参数:

parent -- Father widget it nested in.
name -- Name of the widget.
x -- X-axis coordinate relative to parent widget.
y -- Y-axis coordinate relative to parent widget.
w -- Width.
h -- Height.
note_length -- Length of each note.
space -- Space of each note.
dir -- Direction of the list.
note_design -- Note design callback function.
design_param -- Design parameter.
create_bar -- Whether to create a bar.

返回:

Widget object pointer.

void gui_list_set_style(gui_list_t *list, LIST_STYLE style)

Set list moving style.

参数:

list -- Pointer to the list widget.
style -- Moving style of the list.

void gui_list_set_factor(gui_list_t *list, float factor)

Set list deceleration factor, which defaults to 0.05.

参数:

list -- Pointer to the list widget.
factor -- Deceleration factor.

void gui_list_set_offset(gui_list_t *list, int16_t offset)

Set list offset, can be used to change list initial position.

参数:

list -- Pointer to the list widget.
offset -- List offset.

void gui_list_set_bar_color(gui_list_t *list, gui_color_t color)

Set list bar color.

参数:

list -- Pointer to the list widget.
color -- List bar color.

void gui_list_set_note_num(gui_list_t *list, uint16_t num)

Set note number of list.

参数:

list -- Pointer to the list widget.
num -- Specific number, must be a nonnegative number.

void gui_list_set_card_stack_location(gui_list_t *list, int16_t location)

Set card stack location, only valid when list style is LIST_CARD.

参数:

list -- Pointer to the list widget.
location -- Distance from stack location to the screen bottom of right.

void gui_list_set_out_scope(gui_list_t *list, int16_t out_scope)

Set out scope of list, which is the distance that can be slightly exceeded when scrolling.

参数:

list -- Pointer to the list widget.
out_scope -- Out scope of list.

void gui_list_set_auto_align(gui_list_t *list, bool auto_align)

Set auto align of list, which is used to automatically align notes when the list stops moving.

参数:

list -- Pointer to the list widget.
auto_align -- True: enable auto align, false: disable auto align.

void gui_list_set_inertia(gui_list_t *list, bool inertia)

Set inertia of list, which is used to enable inertia effect while tp released.

参数:

list -- Pointer to the list widget.
inertia -- Default is true. True: enable inertia, false: disable inertia.

void gui_list_enable_loop(gui_list_t *list, bool loop)

Set loop of list, which is used to enable loop effect. Only valid when list total length is greater than list width or height. Don't enable loop when list style is LIST_CARD.

参数:

list -- Pointer to the list widget.
loop -- Default is false. True: enable loop, false: disable loop.

struct gui_list_t

List Structure.

Public Members

gui_obj_t base

uint32_t dir

uint32_t style

uint32_t auto_align

uint32_t inertia

uint32_t loop

uint32_t need_update_bar

uint32_t note_num

uint32_t space

uint16_t note_length

int16_t speed

int16_t record[5]

float factor

int offset

int hold

int total_length

int16_t out_scope

int16_t card_stack_location

int16_t max_created_note_index

int16_t last_created_note_index

void (*note_design)(gui_obj_t *obj, void *param)

void *design_param

gui_img_t *bar

void *bar_data

gui_color_t bar_color

uint8_t checksum

struct gui_list_note_t

List Note Structure.

Public Members

gui_obj_t base

int start_x

int start_y

int t_x

int t_y

uint16_t animate_cnt

bool is_speed_positive

int16_t index