Calendar (lv_calendar)¶
Overview¶
The Calendar object is a classic calendar which can:
highlight the current day
highlight any user-defined dates
display the name of the days
go the next/previous month by button click
highlight the clicked day
Parts and Styles¶
The calendar's main part is called LV_CALENDAR_PART_BG
. It draws a background using the typical background style properties.
Besides the following virtual parts exist:
LV_CALENDAR_PART_HEADER
The upper area where the current year and month's name is shown. It also has buttons to move the next/previous month. It uses typical background properties plus padding to adjust its size and margin to set the distance from the top of the calendar and the day names below it.LV_CALENDAR_PART_DAY_NAMES
Shows the name of the days below the header. It uses the text style properties padding to keep some distance from the background (left, right), header (top) and dates (bottom).LV_CALENDAR_PART_DATES
Show the date numbers from 1..28/29/30/31 (depending on current month). Different "state" of the states are drawn according to the states defined in this part:normal dates: drawn with
LV_STATE_DEFAULT
stylepressed date: drawn with
LV_STATE_PRESSED
styletoday: drawn with
LV_STATE_FOCUSED
stylehighlighted dates: drawn with
LV_STATE_CHECKED
style
Usage¶
Overview¶
To set and get dates in the calendar, the lv_calendar_date_t
type is used 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, &today_date)
function.
Shown date¶
To set the shown date, use lv_calendar_set_shown_date(calendar, &shown_date)
;
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)
.
Only the arrays 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", ...};
Name of the months¶
Similarly to day_names
, the name of the month can be set with lv_calendar_set_month_names(calendar, month_names_array)
.
Events¶
Besides the Generic events, the following Special events are sent by the calendars: LV_EVENT_VALUE_CHANGED is sent when the current month has changed.
In Input device related events, lv_calendar_get_pressed_date(calendar)
tells which day is currently being pressed or return NULL
if no date is pressed.
Example¶
C¶
Calendar with day select¶
code
#include "../../../lv_examples.h"
#include <stdio.h>
#if LV_USE_CALENDAR
static void event_handler(lv_obj_t * obj, lv_event_t event)
{
if(event == LV_EVENT_VALUE_CHANGED) {
lv_calendar_date_t * date = lv_calendar_get_pressed_date(obj);
if(date) {
printf("Clicked date: %02d.%02d.%d\n", date->day, date->month, date->year);
}
}
}
void lv_ex_calendar_1(void)
{
lv_obj_t * calendar = lv_calendar_create(lv_scr_act(), NULL);
lv_obj_set_size(calendar, 235, 235);
lv_obj_align(calendar, NULL, LV_ALIGN_CENTER, 0, 0);
lv_obj_set_event_cb(calendar, event_handler);
/*Make the date number smaller to be sure they fit into their area*/
lv_obj_set_style_local_text_font(calendar, LV_CALENDAR_PART_DATE, LV_STATE_DEFAULT, lv_theme_get_font_small());
/*Set today's date*/
lv_calendar_date_t today;
today.year = 2018;
today.month = 10;
today.day = 23;
lv_calendar_set_today_date(calendar, &today);
lv_calendar_set_showed_date(calendar, &today);
/*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 = 2018;
highlighted_days[0].month = 10;
highlighted_days[0].day = 6;
highlighted_days[1].year = 2018;
highlighted_days[1].month = 10;
highlighted_days[1].day = 11;
highlighted_days[2].year = 2018;
highlighted_days[2].month = 11;
highlighted_days[2].day = 22;
lv_calendar_set_highlighted_dates(calendar, highlighted_days, 3);
}
#endif
MicroPython¶
Calendar with day select¶
Click to try in the simulator!![lv_ex_calendar_1](https://raw.githubusercontent.com/lvgl/lv_examples/9ebc61df6b7be07bd2fb4257fec49bf0dd178e2d/lv_ex_calendar_1/lv_ex_calendar_1.png)
code
def event_handler(source,evt):
if evt == lv.EVENT.VALUE_CHANGED:
date = lv.calendar.get_pressed_date(source)
if date:
print("Clicked date: %02d.%02d.%02d"%(date.day, date.month, date.year))
# create a calendar
calendar = lv.calendar(lv.scr_act(),None)
calendar.set_size(235,235)
calendar.align(None,lv.ALIGN.CENTER,0,0)
calendar.set_event_cb(event_handler)
# Make the date number smaller to be sure they fit into their area
calendar.set_style_local_text_font(lv.calendar.PART.DATE,lv.STATE.DEFAULT,lv.theme_get_font_small())
today = lv.calendar_date_t()
today.year = 2020;
today.month = 10;
today.day = 5
calendar.set_today_date(today)
calendar.set_showed_date(today)
# Highlight a few days
highlighted_days=[]
for i in range(3):
highlighted_days.append(lv.calendar_date_t())
highlighted_days[0].year=2020
highlighted_days[0].month=10
highlighted_days[0].day=6
highlighted_days[1].year=2020
highlighted_days[1].month=10
highlighted_days[1].day=11
highlighted_days[2].year=2020
highlighted_days[2].month=10
highlighted_days[2].day=22
calendar.set_highlighted_dates(highlighted_days,3)
API¶
Typedefs
-
typedef uint8_t
lv_calendar_part_t
¶
Enums
Functions
-
lv_obj_t *
lv_calendar_create
(lv_obj_t *par, const lv_obj_t *copy)¶ Create a calendar objects
- Parameters
par -- pointer to an object, it will be the parent of the new calendar
copy -- pointer to a calendar object, if not NULL then the new object will be copied from it
- Returns
pointer to the created calendar
-
void
lv_calendar_set_today_date
(lv_obj_t *calendar, lv_calendar_date_t *today)¶ Set the today's date
- Parameters
calendar -- pointer to a calendar object
today -- pointer to an
lv_calendar_date_t
variable containing the date of today. The value will be saved it can be local variable too.
-
void
lv_calendar_set_showed_date
(lv_obj_t *calendar, lv_calendar_date_t *showed)¶ Set the currently showed
- Parameters
calendar -- pointer to a calendar object
showed -- pointer to an
lv_calendar_date_t
variable containing the date to show. The value will be saved it can be local variable too.
-
void
lv_calendar_set_highlighted_dates
(lv_obj_t *calendar, lv_calendar_date_t highlighted[], uint16_t date_num)¶ Set the highlighted dates
- Parameters
calendar -- pointer to a calendar object
highlighted -- pointer to an
lv_calendar_date_t
array containing the dates. ONLY A POINTER WILL BE SAVED! CAN'T BE LOCAL ARRAY.date_num -- number of dates in the array
-
void
lv_calendar_set_day_names
(lv_obj_t *calendar, const char **day_names)¶ Set the name of the days
- Parameters
calendar -- 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.
-
void
lv_calendar_set_month_names
(lv_obj_t *calendar, const char **month_names)¶ Set the name of the month
- Parameters
calendar -- pointer to a calendar object
month_names -- pointer to an array with the names. E.g.
const char * days[12] = {"Jan", "Feb", ...}
Only the pointer will be saved so this variable can't be local which will be destroyed later.
-
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.
-
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_pressed_date
(const lv_obj_t *calendar)¶ Get the pressed date.
- Parameters
calendar -- pointer to a calendar object
- Returns
pointer to an
lv_calendar_date_t
variable containing the pressed date.NULL
if not date pressed (e.g. the header)
-
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
-
const char **
lv_calendar_get_day_names
(const lv_obj_t *calendar)¶ Get the name of the days
- Parameters
calendar -- pointer to a calendar object
- Returns
pointer to the array of day names
-
const char **
lv_calendar_get_month_names
(const lv_obj_t *calendar)¶ Get the name of the month
- Parameters
calendar -- pointer to a calendar object
- Returns
pointer to the array of month names
-
uint8_t
lv_calendar_get_day_of_week
(uint32_t year, uint32_t month, uint32_t day)¶ Get the day of the week
- Parameters
year -- a year
month -- a month (1..12)
day -- a day (1..31)
- Returns
[0..6] which means [Sun..Sat] or [Mon..Sun] depending on LV_CALENDAR_WEEK_STARTS_MONDAY
-
struct
lv_calendar_date_t
¶ - #include <lv_calendar.h>
Represents a date on the calendar object (platform-agnostic).
-
struct
lv_calendar_ext_t
¶ Public Members
-
lv_calendar_date_t
today
¶
-
lv_calendar_date_t
showed_date
¶
-
lv_calendar_date_t *
highlighted_dates
¶
-
int8_t
btn_pressing
¶
-
uint16_t
highlighted_dates_num
¶
-
lv_calendar_date_t
pressed_date
¶
-
const char **
day_names
¶
-
const char **
month_names
¶
-
lv_style_list_t
style_header
¶
-
lv_style_list_t
style_day_names
¶
-
lv_style_list_t
style_date_nums
¶
-
lv_calendar_date_t