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_BTNMATRIX_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.
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_RES_OK
if there is a valid pressed date, elseLV_RES_INV
.
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.
Arrow buttons¶
lv_calendar_header_arrow_create(calendar)
creates a header that contains a left and right arrow on the sides and a text with the current year and month between them.
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
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_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
-
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).
-
struct lv_calendar_t¶
Public Members
-
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]¶
-
lv_calendar_date_t today¶