init Files
This commit is contained in:
153
libraries/lvgl/docs/widgets/calendar.rst
Normal file
153
libraries/lvgl/docs/widgets/calendar.rst
Normal file
@@ -0,0 +1,153 @@
|
||||
.. _lv_calendar:
|
||||
|
||||
======================
|
||||
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.
|
||||
|
||||
.. _lv_calendar_parts_and_styles:
|
||||
|
||||
Parts and Styles
|
||||
****************
|
||||
|
||||
The calendar object uses the `Button matrix </widgets/buttonmatrix>`__
|
||||
object under the hood to arrange the days into a matrix.
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties.
|
||||
- :cpp:enumerator:`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 :cpp:enumerator:`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.
|
||||
|
||||
.. _lv_calendar_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Some functions use the :cpp:struct:`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
|
||||
:cpp:expr:`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
|
||||
:cpp:expr:`lv_calendar_set_shown_date(calendar, year, month)`
|
||||
|
||||
Highlighted days
|
||||
----------------
|
||||
|
||||
The list of highlighted dates should be stored in a
|
||||
:cpp:struct:`lv_calendar_date_t` array loaded by
|
||||
:cpp:expr:`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
|
||||
:cpp:expr:`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.
|
||||
|
||||
Custom year list
|
||||
----------------
|
||||
|
||||
Sets a custom year list with :cpp:expr:`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.
|
||||
|
||||
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 :cpp:expr:`lv_calendar_set_chinese_mode(calendar, true)` to enable it.
|
||||
|
||||
.. _lv_calendar_events:
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent if a date is clicked.
|
||||
:cpp:expr:`lv_calendar_get_pressed_date(calendar, &date)` set ``date`` to the
|
||||
date currently being pressed. Returns :cpp:enumerator:`LV_RESULT_OK` if there is a
|
||||
valid pressed date, else :cpp:enumerator:`LV_RESULT_INVALID`.
|
||||
|
||||
Learn more about :ref:`events`.
|
||||
|
||||
.. _lv_calendar_keys:
|
||||
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to dates
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected date
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
.. _lv_calendar_header:
|
||||
|
||||
Headers
|
||||
*******
|
||||
|
||||
**From v8.1 the header is added directly into the Calendar widget and
|
||||
the API of the headers has been changed.**
|
||||
|
||||
Arrow buttons
|
||||
-------------
|
||||
|
||||
:cpp:expr:`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
|
||||
---------
|
||||
|
||||
:cpp:expr:`lv_calendar_header_dropdown_create(calendar)` creates a header that
|
||||
contains 2 drop-drown lists: one for the year and another for the month.
|
||||
|
||||
.. _lv_calendar_example:
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../examples/widgets/calendar/index.rst
|
||||
|
||||
.. _lv_calendar_api:
|
||||
|
||||
API
|
||||
***
|
||||
Reference in New Issue
Block a user