Labs / LVGL / 03 Quick Start Example - Control Section (Based on Web Simulator and LVGL v9.0)

13. Calendar

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents
API namePurpose
initConstruct a calendar widget, bound to the parent container
set_today_dateSet today's date of the calendar
set_highlighted_datesSet the dates to be highlighted in the calendar
set_day_namesSet the weekday names at the top of the calendar
get_btnmatrixGet the internal button matrix object of the calendar
get_today_dateGet today's date set in the calendar
get_showed_dateGet the year and month currently displayed by the calendar
get_highlighted_datesGet the list of highlighted dates of the calendar
get_highlighted_dates_numGet the total number of highlighted dates
get_pressed_dateGet the date currently selected by clicking
header_dropdown_set_year_listSet the year list of the drop-down in the calendar header

The list of actually tested and available APIs is as follows:

API nameMeaningInput parametersReturn value
lv.calendar.__init__Construct a calendar widget, bound to the specified parent containerparent: lv.obj (e.g., the screen object scr)lv.calendar (calendar widget object)
set_today_dateSet today's date of the calendarThree int parameters:
year, month, day
No return value
set_showed_dateSet the year and month currently displayed by the calendarTwo int parameters:
year, month
No return value
set_highlighted_datesSet the dates to be highlighted in the calendar1. Highlighted date list: list of lv_calendar_date_t objects (each object must have its year/month/day attributes configured);
2. date_num: int, the number of highlighted dates
No return value
get_btnmatrixGet the internal button matrix object of the calendarNo input parameterslv.buttonmatrix
(button matrix object)
get_today_dateGet the today's date already set in the calendarNo input parameterslv_calendar_date_t object
(with year/month/day attributes)
get_showed_dateGet the year and month currently displayed by the calendarNo input parameterslv_calendar_date_t object
(with year/month attributes)
get_highlighted_datesGet the highlighted dates of the calendar (environment limitation: only the first highlighted date is returned)No input parameterslv_calendar_date_t object
(with year/month/day attributes)
get_highlighted_dates_numGet the total number of highlighted dates in the calendarNo input parametersint (number of highlighted dates)
header_dropdown_set_year_listSet the year list of the drop-down in the calendar headerA single str parameter: year string (separate different years with the newline character \n, e.g., "2020\n2021\n2022")No return value

13.1 Basic Calendar Initialization

import display_driver
import lvgl as lv

# Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  

#Create a calendar object
calendar = lv.calendar(scr)
#Set the size
calendar.set_size(250, 250)
#Center it
calendar.center()
# Set today's date (March 16, 2026)
calendar.set_today_date(2026, 03, 16)
 # Set the displayed year and month directly
calendar.set_showed_date(2026, 03)

# Load the screen
lv.screen_load(scr)
2026 3 16 1 11 13.2

13.2 Highlighted Date Setting and Query

The following code simulates the actual scenario of "marking holidays / important schedules", which is the most commonly used business function of the calendar:

import display_driver
import lvgl as lv

# Initialize the environment
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  

calendar = lv.calendar(scr)
calendar.set_size(300, 300)
calendar.center()
calendar.set_today_date(2026, 3, 16)
# Set the displayed year and month directly
calendar.set_showed_date(2026, 03)

# ========== Core API calls ==========
# 1. Construct the highlighted date objects (must use lv_calendar_date_t, required by the environment)
# Highlight March 8 (Women's Day) and March 20 (important meeting)
highlight_date1 = lv.calendar_date_t()
highlight_date1.year, highlight_date1.month, highlight_date1.day = 2026, 3, 8

highlight_date2 = lv.calendar_date_t()
highlight_date2.year, highlight_date2.month, highlight_date2.day = 2026, 3, 20

# 2. set_highlighted_dates: set the highlighted dates (arguments: list of date objects + count int)
calendar.set_highlighted_dates([highlight_date1, highlight_date2], 2)

# 3. get_highlighted_dates_num: get the total number of highlighted dates (returns int)
highlight_count = calendar.get_highlighted_dates_num()
print(f"Total Highlighted Dates: {highlight_count}")

# 4. get_highlighted_dates: get the first highlighted date (environment limitation: only returns the first one)
first_highlight = calendar.get_highlighted_dates()
print(f"First Highlighted Date: {first_highlight.year}-{first_highlight.month}-{first_highlight.day}")

# Load the screen
lv.screen_load(scr)
2026 3 8 4 11 16 20

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.