Calendar (lv_calendar)

Overview

The Calendar Widget is a classic calendar which can:

show the days of any month in a 7x7 matrix;
show the name of the days;
highlight the current day (today);
highlight any user-defined dates.

The Calendar is added to the default group (if one is set). Calendar is an editable Widget which allow selecting and clicking the dates with encoder or keyboard navigation as well as pointer-type input devices.

To make the Calendar flexible, by default it does not show the current year or month. Instead, there are optional "headers" that can be attached to the calendar.

Parts and Styles

The calendar Widget uses the Button Matrix Widget under the hood to arrange the days into a matrix.

LV_PART_MAIN Calendar background. Uses the typical background style properties.
LV_PART_ITEMS Refers to dates and day names. Button matrix control flags are set to differentiate the buttons and a custom drawer event is added to modify the properties of the buttons as follows:
- day names have no border, no background and are drawn with a gray color
- days of the previous and next month have the LV_BUTTONMATRIX_CTRL_DISABLED flag
- today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color.

Usage

Some functions use the lv_calendar_date_t type which is a structure with year, month and day fields.

Current date

To set the current date (today), use the lv_calendar_set_today_date(calendar, year, month, day) function. month needs to be in 1..12 range and day in 1..31 range.

Month shown

To set the shown date, use lv_calendar_set_month_shown(calendar, year, month)

Highlighted days

The list of highlighted dates should be stored in a lv_calendar_date_t array and applied to the Calendar by calling lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num). Only the array's pointer will be saved so the array should be have static or global scope.

Names of days

The names of the days can be adjusted with lv_calendar_set_day_names(calendar, day_names) where day_names looks like const char * day_names[7] = {"Su", "Mo", ...}; Only the pointer of the day names is saved so the array should have static or global scope.

Custom year list

Set a custom year list with lv_calendar_header_dropdown_set_year_list(calendar, years_list) where years_list is a pointer to the custom years list. It can be a constant string like static const char * years = "2023\n2022\n2021\n2020\n2019";, or can be generated dynamically into a buffer as well. Calendar stores these in a Drop-Down List Widget via lv_dropdown_set_options() so the passed string pointer can be supplied by a local variable or buffer and does not need to persist beyond the call.

Chinese calendar

The Chinese calendar is a traditional cultural tool that integrates elements such as the lunar calendar, solar terms, and traditional festivals. It is widely used in Chinese social life, helping people understand the dates of the lunar calendar, arrange festival activities, and inherit the excellent traditional culture of the Chinese nation. Whether in families, businesses, or education, the Chinese calendar plays an irreplaceable role, enabling people to better understand and appreciate the charm of Chinese traditional culture.

If you want to use the Chinese calendar, please use lv_calendar_set_chinese_mode(calendar, true) to enable it.

Events

LV_EVENT_VALUE_CHANGED Sent if a date is clicked. lv_calendar_get_pressed_date(calendar, &date) to set date to the date currently being pressed. Returns LV_RESULT_OK if there is a valid pressed date; otherwise it returns LV_RESULT_INVALID.

Keys

LV_KEY_RIGHT/UP/LEFT/RIGHT To navigate among the buttons to dates
LV_KEY_ENTER To press/release the selected date

Headers

From LVGL v8.1 onward, the header is added directly into the Calendar Widget and the API of the headers has been changed.

Arrow buttons

lv_calendar_header_arrow_create(calendar) creates a header that contains a left and right arrow on the sides and text between the arrows showing the current year and month.

Drop-down

lv_calendar_header_dropdown_create(calendar) creates a header that contains 2 Drop-Drown List Widgets for the year and month.

Example

Calendar with header

#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_screen_active());
    lv_obj_set_size(calendar, 185, 230);
    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_month_shown(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
}

#endif

Chinese calendar

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

void lv_example_calendar_2(void)
{
    lv_obj_t  * calendar = lv_calendar_create(lv_screen_active());
    lv_obj_set_size(calendar, 300, 300);
    lv_obj_align(calendar, LV_ALIGN_TOP_MID, 0, 0);

    lv_calendar_set_today_date(calendar, 2024, 03, 22);
    lv_calendar_set_month_shown(calendar, 2024, 03);

#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_chinese_mode(calendar, true);
    lv_obj_set_style_text_font(calendar, &lv_font_simsun_14_cjk, LV_PART_MAIN);
}

#else

void lv_example_calendar_2(void)
{
    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, "chinese calendar is not enabled");
    lv_obj_center(label);
}

#endif

API

lv_calendar.h

lv_calendar_chinese.h

lv_api_map_v9_1.h

lv_calendar_header_arrow.h

lv_types.h

lv_calendar_header_dropdown.h