# Calendar (lv_calendar) (/widgets/calendar)



Overview [#overview]

The Calendar Widget 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 one is set). Calendar is
an editable Widget which allows selecting and clicking the dates with
encoder or keyboard navigation as well as pointer-type input devices.

To make the Calendar flexible, by default it does not show the current
year or month. Instead, there are optional "headers" that can be
attached to the calendar.

Parts and Styles [#parts-and-styles]

The calendar Widget uses the [Button Matrix](/widgets/buttonmatrix)
Widget under the hood to arrange the days into a matrix.

* <ApiLink name="LV_PART_MAIN" /> Calendar background. Uses the [typical
  background style properties](/common-widget-features/styles/overview).
* <ApiLink name="LV_PART_ITEMS" /> Refers to dates and day names. Button matrix
  control flags are set to differentiate the buttons and a custom drawer event is
  added to modify the properties of the buttons as follows:

  * day names have no border, no background and are drawn with a gray color
  * days of the previous and next month have the <ApiLink name="LV_BUTTONMATRIX_CTRL_DISABLED" /> flag
  * today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color.

Usage [#usage]

Some functions use the <ApiLink name="lv_calendar_date_t" /> type which is a structure
with `year`, `month` and `day` fields.

Current date [#current-date]

To set the current date (today), use the
<ApiLink name="lv_calendar_set_today_date" display="lv_calendar_set_today_date(calendar, year, month, day)" /> function.
`month` needs to be in 1..12 range and `day` in 1..31 range.

Month shown [#month-shown]

To set the shown date, use

<ApiLink name="lv_calendar_set_month_shown" display="lv_calendar_set_month_shown(calendar, year, month)" />

Highlighted days [#highlighted-days]

The list of highlighted dates should be stored in a
<ApiLink name="lv_calendar_date_t" /> array and applied to the Calendar by calling
<ApiLink name="lv_calendar_set_highlighted_dates" display="lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num)" />.
Only the array's pointer will be saved so the array should be have static or
global scope.

Names of days [#names-of-days]

The names of the days can be adjusted with
<ApiLink name="lv_calendar_set_day_names" display="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 array should have static or
global scope.

Custom year list [#custom-year-list]

Set a custom year list with <ApiLink name="lv_calendar_header_dropdown_set_year_list" display="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.  Calendar stores these in a
Drop-Down List Widget via <ApiLink name="lv_dropdown_set_options" /> so the passed string
pointer can be supplied by a local variable or buffer and does not need to persist
beyond the call.

Chinese calendar [#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 <ApiLink name="lv_calendar_set_chinese_mode" display="lv_calendar_set_chinese_mode(calendar, true)" /> to enable it.

Events [#events]

* <ApiLink name="LV_EVENT_VALUE_CHANGED" /> Sent if a date is clicked.
  <ApiLink name="lv_calendar_get_pressed_date" display="lv_calendar_get_pressed_date(calendar, &date)" /> to set `date` to the
  date currently being pressed. Returns <ApiLink name="LV_RESULT_OK" /> if there is a
  valid pressed date; otherwise it returns <ApiLink name="LV_RESULT_INVALID" />.

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

* `LV_KEY_DOWN/UP/LEFT/RIGHT` To navigate among the buttons to dates
* <ApiLink name="LV_KEY_ENTER" /> To press/release the selected date

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Headers [#headers]

**From LVGL v8.1 onward, the header is added directly into the Calendar Widget and
the API of the headers has been changed.**

Arrow buttons [#arrow-buttons]

<ApiLink name="lv_calendar_add_header_arrow" display="lv_calendar_add_header_arrow(calendar)" /> creates a header that
contains a left and right arrow on the sides and text between the arrows showing the
current year and month.

Drop-down [#drop-down]

<ApiLink name="lv_calendar_add_header_dropdown" display="lv_calendar_add_header_dropdown(calendar)" /> creates a header that
contains 2 Drop-Drown List Widgets for the year and month.

Examples [#examples]

Calendar with header [#calendar-with-header]

<LvglExample name="lv_example_calendar_1" path="widgets/calendar/lv_example_calendar_1" />

Chinese calendar [#chinese-calendar-1]

<LvglExample name="lv_example_calendar_2" path="widgets/calendar/lv_example_calendar_2" />

API [#api]