1# Calendar (lv_calendar)
2
3**From v8.1 the header is added directly into the Calendar widget and the API of the headers has been changed.**
4
5## Overview
6
7The Calendar object is a classic calendar which can:
8- show the days of any month in a 7x7 matrix
9- Show the name of the days
10- highlight the current day (today)
11- highlight any user-defined dates
12
13The 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.
14
15To 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.
16
17## Parts and Styles
18The Calendar is composed of 3 widegets
19- Container: A rectangle which is a container for the *Header* and the *Days*. Uses only `LV_PART_MAIN` where all the background related style properties are working.
20- Days: It's a [Button matrix](/widgets/core/btnmatrix) object under the hood to arrange the days into a matrix. `lv_calendar_get_btnmatrix(calendar)` can be used to get it.
21    - `LV_PART_MAIN` The background of the calendar. Uses all the background related style properties.
22    - `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:
23       - day names have no border, no background and drawn with a gray color
24       - days of the previous and next month have `LV_BTNMATRIX_CTRL_DISABLED` flag
25       - today has a thicker border with the theme's primary color
26       - highlighted days have some opacity with the theme's primary color.
27- Header: Not created by default, the details are up to the given header.
28
29## Usage
30
31Some functions use the `lv_calendar_date_t` type which is a structure with `year`, `month` and `day` fields.
32
33### Current date
34To 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.
35
36### Shown date
37To set the shown date, use `lv_calendar_set_shown_date(calendar, year, month)`;
38
39### Highlighted days
40
41The 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)`.
42Only the array's pointer will be saved so the array should be a static or global variable.
43
44### Name of the days
45The 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", ...};`
46Only the pointer of the day names is saved so the elements should be static, global or constant variables.
47
48### Custom year list
49
50Sets a custom year list with `lv_calendar_header_dropdown_set_year_list(calendar, years_list)`
51where ``years_list`` is a pointer to the custom years list. It can be a constant string
52like ``static const char * years = "2023\n2022\n2021\n2020\n2019";``,
53or can be generated dynamically into a buffer as well.
54
55## Events
56- `LV_EVENT_VALUE_CHANGED` Sent if a date is clicked. `lv_calendar_get_pressed_date(calendar, &date)` set `date` to the date currently being pressed. Returns `LV_RES_OK` if there is a valid pressed date, else `LV_RES_INV`.
57
58Learn more about [Events](/overview/event).
59
60## Keys
61- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to dates
62- `LV_KEY_ENTER` To press/release the selected date
63
64Learn more about [Keys](/overview/indev).
65
66## Headers
67
68### Arrow buttons
69
70`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.
71
72
73### Drop-down
74`lv_calendar_header_dropdown_create(calendar)` creates a header that contains 2 drop-drown lists: one for the year and another for the month.
75
76
77## Example
78
79```eval_rst
80
81.. include:: ../../../examples/widgets/calendar/index.rst
82
83```
84
85## API
86
87```eval_rst
88
89.. doxygenfile:: lv_calendar.h
90  :project: lvgl
91
92```
93