List

The list widget is a container for any number of list note, horizontally or vertically. And each note, which is dynamic created for saving memory and CPU usage, can have other widgets added to it, such as text widgets, image widgets, etc. Users can swipe up, down, left, or right to access other widgets added to the list note.

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

Usage

Create List Widget

The gui_list_create() function can be used to create a list widget, in which the scroll bar is optional, and the next level of the list widget can only be a note widget. In note_design, the corresponding child widget could be designed according to the index of the list widget to dynamically create the note widget. The total length of the list widget is determined by the number of note added, the length of the note, and the space between the tables; as more tables are added, the length increases.

Set List Widget Style

The gui_list_set_style() function can be used to set list moving style. The default is LIST_CLASSIC, and the available styles include the following:

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;

Set Card Style Stacking Position

The gui_list_set_card_stack_location() function can be used to set card style stacking position.

Set Circle Style Radius

The gui_list_set_circle_radius() function can be used to set circle style radius.

Example

#include "guidef.h"
#include "string.h"
#include "stdio.h"
#include "stdlib.h"
#include "gui_server.h"
#include "gui_components_init.h"
#include "gui_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_rounded_rect_t *canvas = gui_rect_create(obj, "note", 0, 0, 480, length, 0, color[index]);
#endif

#ifdef RUN_HORIZONTAL_ZOOM_STYLE
    gui_rounded_rect_t *canvas = gui_rect_create(obj, "note", 0, 0, length, 480, 0, color[index]);
#endif

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

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

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

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

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

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

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

    /* VERTICAL CIRCLE STYLE */
#ifdef RUN_VERTICAL_CIRCLE_STYLE

    gui_list_t *list = gui_list_create(gui_obj_get_root(), "list", 0, 0, 0, 480, 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);
    gui_list_set_circle_radius(list, 240);
    gui_list_set_auto_align(list, true);
    // gui_list_keep_note_alive(list, true);
    gui_list_enable_loop(list, true);
    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);
    gui_list_set_out_scope(list, 100);
    gui_list_set_auto_align(list, true);
    gui_list_enable_loop(list, true);
    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

    return 0;
}

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.

Parameters:

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.

Returns:

Widget object pointer.

void gui_list_set_style(gui_list_t *list, LIST_STYLE style)

Set list moving style.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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

void gui_list_set_circle_radius(gui_list_t *list, uint16_t radius)

Set circle radius, only valid when list style is LIST_CIRCLE, default is half of list width or height.

Parameters:

list -- Pointer to the list widget.
radius -- Circle radius.

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.

Parameters:

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.

Parameters:

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.

Parameters:

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.

Parameters:

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

void gui_list_enable_area_display(gui_list_t *list, bool enable)

Enable area display of list, which is used to decide note auto-creation range.

Parameters:

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

void gui_list_keep_note_alive(gui_list_t *list, bool enable)

Set keep note alive, which is used to keep notes alive in memory when the list is scrolled. Can't enable keep note alive when list enables loop.

Parameters:

list -- Pointer to the list widget.
enable -- True: enable keep note alive, false: disable keep note alive. Default is false.

void gui_list_scroll_to_note(gui_list_t *list, uint16_t note_index)

Scroll to a specific note with smooth animation. Uses exponential ease to smoothly animate the list offset until the target note is in view position. For loop mode, automatically picks the shortest path around the ring.

Parameters:

list -- Pointer to the list widget.
note_index -- Index of the target note (0-based, must be < note_num).

void gui_list_jump_to_note(gui_list_t *list, uint16_t note_index)

Jump to a specific note instantly without animation. Sets the list offset directly so the target note is in view position. For loop mode, picks the shortest path and wraps offset if needed.

Parameters:

list -- Pointer to the list widget.
note_index -- Index of the target note (0-based, must be < note_num).

uint16_t gui_list_get_current_note(gui_list_t *list)

Get the index of the note currently in view position. Returns the note index closest to the primary display position (top for Default, center for ZOOM_CYLINDER, bottom for CARD).

Parameters:: list -- Pointer to the list widget.
Returns:: Current note index (0 to note_num-1).

void gui_list_enable_scroll(gui_list_t *list, bool enable)

Enable scroll of list.

Parameters:

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

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

uint32_t area_display

uint32_t keep_note_alive

uint32_t scroll_to_active

uint32_t enable_scroll

uint16_t circle_radius

uint16_t note_length

int16_t speed

int16_t record[5]

float factor

int offset

int hold

int scroll_target

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

List

Usage

Create List Widget

Set List Widget Style

Set List Widget Deceleration Factor

Set List Widget Offset

Set List Widget Scroll Bar Color

Set List Widget Note Number

Set Card Style Stacking Position

Set Circle Style Radius

Set List Widget Out Scope

Set List Widget Auto Align

Set List Widget Inertia

Set List Widget Loop

Set List Widget Area Display

Set List Widget Keep Note Alive

Example

API