Calendar (lv_calendar)
Overview
The Calendar object 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 it is set). Calendar is an editable object which allow selecting and clicking the dates with encoder navigation too.
To make the Calendar flexible, by default it doesn't show the current year or month. Instead, there are optional "headers" that can be attached to the calendar.
Parts and Styles
The calendar object uses the Button matrix object under the hood to arrange the days into a matrix.
LV_PART_MAIN
The background of the calendar. Uses all the background related style properties.LV_PART_ITEMS
Refers to the dates and day names. Button matrix control flags are set to differentiate the buttons and a custom drawer event is added modify the properties of the buttons as follows:day names have no border, no background and drawn with a gray color
days of the previous and next month have
LV_BUTTONMATRIX_CTRL_DISABLED
flagtoday 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.
Shown date
To set the shown date, use lv_calendar_set_shown_date(calendar, year, month)
Highlighted days
The list of highlighted dates should be stored in a
lv_calendar_date_t
array loaded by
lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num).
Only the array's pointer will be saved so the array should be a static
or global variable.
Name of the days
The name 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 elements should be static,
global or constant variables.
Custom year list
Sets 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.
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) setdate
to the date currently being pressed. ReturnsLV_RESULT_OK
if there is a valid pressed date, elseLV_RESULT_INVALID
.
Learn more about Events.
Keys
LV_KEY_RIGHT/UP/LEFT/RIGHT
To navigate among the buttons to datesLV_KEY_ENTER
To press/release the selected date
Learn more about Keys.
Headers
From v8.1 the header is added directly into the Calendar widget and the API of the headers has been changed.
Drop-down
lv_calendar_header_dropdown_create(calendar) creates a header that contains 2 drop-drown lists: one for the year and another for the month.
Example
Calendar with header
C code
View on GitHub#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_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
}
#endif
Chinese calendar
C code
View on GitHub#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_showed_date(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