日历 (lv_calendar)¶

概述¶

日历对象是一个经典的日历，可以：

以 7x7 矩阵显示任意月份的日期
显示日期名称
突出显示当前日期（今天）
突出显示任何用户定义的日期

日历会添加到默认组（如果已设置）。日历是一个可编辑的对象，允许通过编码器导航选择和点击日期。

为了使日历更灵活，默认情况下它不会显示当前年份或月份。相反，可以将可选的“标题”附加到日历中。

部件和样式¶

日历对象在底层使用按钮矩阵对象将日期排列成矩阵。

LV_PART_MAIN 日历的背景。使用所有与背景相关的样式属性。
LV_PART_ITEMS 指代日期和日期名称。按钮矩阵控制标志被设置以区分按钮，并添加了一个自定义绘制事件来修改按钮的属性，如下所示：
- 日期名称没有边框、没有背景，并以灰色绘制
- 上个月和下个月的日期具有 LV_BTNMATRIX_CTRL_DISABLED 标志
- 今天的边框更粗，使用主题的主色
- 突出显示的日期具有一些透明度，使用主题的主色。

用法¶

一些函数使用 lv_calendar_date_t 类型，它是一个包含 year、month 和 day 字段的结构。

当前日期¶

要设置当前日期（今天），请使用 lv_calendar_set_today_date(calendar, year, month, day) 函数。month 需要在 1..12 范围内，day 在 1..31 范围内。

显示的日期¶

要设置显示的日期，请使用 lv_calendar_set_shown_date(calendar, year, month)。

突出显示的日期¶

突出显示的日期列表应存储在一个 lv_calendar_date_t 数组中，并通过 lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num) 加载。仅保存数组的指针，因此数组应为静态或全局变量。

日期名称¶

可以使用 lv_calendar_set_day_names(calendar, day_names) 调整日期名称，其中 day_names 类似于 const char * day_names[7] = {"Su", "Mo", ...};。仅保存日期名称的指针，因此元素应为静态、全局或常量变量。

事件¶

LV_EVENT_VALUE_CHANGED 如果点击了某个日期会发送此事件。lv_calendar_get_pressed_date(calendar, &date) 将 date 设置为当前被按下的日期。如果有有效的按下日期，返回 LV_RES_OK，否则返回 LV_RES_INV。

了解更多关于事件的信息。

按键¶

LV_KEY_RIGHT/UP/LEFT/RIGHT 在日期按钮之间导航
LV_KEY_ENTER 按下/释放选定的日期

了解更多关于按键的信息。

标题¶

从 v8.1 开始，标题直接添加到日历小部件中，标题的 API 已更改。

箭头按钮¶

lv_calendar_header_arrow_create(calendar) 创建一个标题，其中包含两侧的左右箭头以及中间显示当前年份和月份的文本。

下拉菜单¶

lv_calendar_header_dropdown_create(calendar) 创建一个标题，其中包含两个下拉列表：一个用于年份，另一个用于月份。

示例¶

带有标题的日历¶

#include "../../lv_examples.h"
#if LV_USE_CALENDAR && LV_BUILD_EXAMPLES

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_current_target(e);

    if(code == LV_EVENT_VALUE_CHANGED) {
        lv_calendar_date_t date;
        if(lv_calendar_get_pressed_date(obj, &date)) {
            LV_LOG_USER("Clicked date: %02d.%02d.%d", date.day, date.month, date.year);
        }
    }
}

void lv_example_calendar_1(void)
{
    lv_obj_t  * calendar = lv_calendar_create(lv_scr_act());
    lv_obj_set_size(calendar, 185, 185);
    lv_obj_align(calendar, LV_ALIGN_CENTER, 0, 27);
    lv_obj_add_event_cb(calendar, event_handler, LV_EVENT_ALL, NULL);

    lv_calendar_set_today_date(calendar, 2021, 02, 23);
    lv_calendar_set_showed_date(calendar, 2021, 02);

    /*Highlight a few days*/
    static lv_calendar_date_t highlighted_days[3];       /*Only its pointer will be saved so should be static*/
    highlighted_days[0].year = 2021;
    highlighted_days[0].month = 02;
    highlighted_days[0].day = 6;

    highlighted_days[1].year = 2021;
    highlighted_days[1].month = 02;
    highlighted_days[1].day = 11;

    highlighted_days[2].year = 2022;
    highlighted_days[2].month = 02;
    highlighted_days[2].day = 22;

    lv_calendar_set_highlighted_dates(calendar, highlighted_days, 3);

#if LV_USE_CALENDAR_HEADER_DROPDOWN
    lv_calendar_header_dropdown_create(calendar);
#elif LV_USE_CALENDAR_HEADER_ARROW
    lv_calendar_header_arrow_create(calendar);
#endif
    lv_calendar_set_showed_date(calendar, 2021, 10);
}

#endif

def event_handler(evt):
    code = evt.get_code()

    if code == lv.EVENT.VALUE_CHANGED:
        source = evt.get_current_target()
        date = lv.calendar_date_t()
        if source.get_pressed_date(date) == lv.RES.OK:
            calendar.set_today_date(date.year, date.month, date.day)
            print("Clicked date: %02d.%02d.%02d"%(date.day, date.month, date.year))


calendar = lv.calendar(lv.scr_act())
calendar.set_size(200, 200)
calendar.align(lv.ALIGN.CENTER, 0, 20)
calendar.add_event_cb(event_handler, lv.EVENT.ALL, None)

calendar.set_today_date(2021, 02, 23)
calendar.set_showed_date(2021, 02)

# Highlight a few days
highlighted_days=[
    lv.calendar_date_t({'year':2021, 'month':2, 'day':6}),
    lv.calendar_date_t({'year':2021, 'month':2, 'day':11}),
    lv.calendar_date_t({'year':2021, 'month':2, 'day':22})
]

calendar.set_highlighted_dates(highlighted_days, len(highlighted_days))

lv.calendar_header_dropdown(calendar)

API¶

Functions

lv_obj_t *lv_calendar_create(lv_obj_t *parent)¶

void lv_calendar_set_today_date(lv_obj_t *obj, uint32_t year, uint32_t month, uint32_t day)¶

Set the today's date

Parameters

obj -- pointer to a calendar object
year -- today's year
month -- today's month [1..12]
day -- today's day [1..31]

void lv_calendar_set_showed_date(lv_obj_t *obj, uint32_t year, uint32_t month)¶

Set the currently showed

Parameters

obj -- pointer to a calendar object
year -- today's year
month -- today's month [1..12]

void lv_calendar_set_highlighted_dates(lv_obj_t *obj, lv_calendar_date_t highlighted[], uint16_t date_num)¶

Set the highlighted dates

Parameters

obj -- pointer to a calendar object
highlighted -- pointer to an lv_calendar_date_t array containing the dates. Only the pointer will be saved so this variable can't be local which will be destroyed later.
date_num -- number of dates in the array

void lv_calendar_set_day_names(lv_obj_t *obj, const char **day_names)¶

Set the name of the days

Parameters

obj -- pointer to a calendar object
day_names -- pointer to an array with the names. E.g. const char * days[7] = {"Sun", "Mon", ...} Only the pointer will be saved so this variable can't be local which will be destroyed later.

lv_obj_t *lv_calendar_get_btnmatrix(const lv_obj_t *obj)¶

Get the button matrix object of the calendar. It shows the dates and day names.

Parameters: obj -- pointer to a calendar object
Returns: pointer to a the button matrix

const lv_calendar_date_t *lv_calendar_get_today_date(const lv_obj_t *calendar)¶

Get the today's date

Parameters: calendar -- pointer to a calendar object
Returns: return pointer to an lv_calendar_date_t variable containing the date of today.

const lv_calendar_date_t *lv_calendar_get_showed_date(const lv_obj_t *calendar)¶

Get the currently showed

Parameters: calendar -- pointer to a calendar object
Returns: pointer to an lv_calendar_date_t variable containing the date is being shown.

lv_calendar_date_t *lv_calendar_get_highlighted_dates(const lv_obj_t *calendar)¶

Get the highlighted dates

Parameters: calendar -- pointer to a calendar object
Returns: pointer to an lv_calendar_date_t array containing the dates.

uint16_t lv_calendar_get_highlighted_dates_num(const lv_obj_t *calendar)¶

Get the number of the highlighted dates

Parameters: calendar -- pointer to a calendar object
Returns: number of highlighted days

lv_res_t lv_calendar_get_pressed_date(const lv_obj_t *calendar, lv_calendar_date_t *date)¶

Get the currently pressed day

Parameters

calendar -- pointer to a calendar object
date -- store the pressed date here

Returns

LV_RES_OK: there is a valid pressed date; LV_RES_INV: there is no pressed data

Variables

const lv_obj_class_t lv_calendar_class¶

struct lv_calendar_date_t¶

#include <lv_calendar.h>

Represents a date on the calendar object (platform-agnostic).

Public Members

uint16_t year¶

int8_t month¶

int8_t day¶: 1..12

struct lv_calendar_t¶

Public Members

lv_obj_t obj¶

lv_obj_t *btnm¶

lv_calendar_date_t today¶

lv_calendar_date_t showed_date¶

lv_calendar_date_t *highlighted_dates¶

uint16_t highlighted_dates_num¶

const char *map[8 * 7]¶

char nums[7 * 6][4]¶