acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
calendar.md (3469B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/extra/calendar.md
      4 ```
      5 # Calendar (lv_calendar)
      6 
      7 ## Overview
      8 
      9 The Calendar object is a classic calendar which can:
     10 - show the days of any month in a 7x7 matrix
     11 - Show the name of the days
     12 - highlight the current day (today)
     13 - highlight any user-defined dates
     14 
     15 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.
     16 
     17 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.
     18 
     19 ## Parts and Styles
     20 The calendar object uses the [Button matrix](/widgets/core/btnmatrix) object under the hood to arrange the days into a matrix.
     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 
     28 ## Usage
     29 
     30 Some functions use the `lv_calendar_date_t` type which is a structure with `year`, `month` and `day` fields.
     31 
     32 ### Current date
     33 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.
     34 
     35 ### Shown date
     36 To set the shown date, use `lv_calendar_set_shown_date(calendar, year, month)`;
     37 
     38 ### Highlighted days
     39 
     40 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)`.
     41 Only the array's pointer will be saved so the array should be a static or global variable.
     42 
     43 ### Name of the days
     44 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", ...};`
     45 Only the pointer of the day names is saved so the elements should be static, global or constant variables.
     46 
     47 ## Events
     48 - `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`.
     49 
     50 Learn more about [Events](/overview/event).
     51 
     52 ## Keys
     53 - `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to dates
     54 - `LV_KEY_ENTER` To press/release the selected date
     55 
     56 Learn more about [Keys](/overview/indev).
     57 
     58 ## Headers
     59 
     60 **From v8.1 the header is added directly into the Calendar widget and the API of the headers has been changed.**
     61 
     62 ### Arrow buttons
     63 
     64 `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.
     65 
     66 
     67 ### Drop-down
     68 `lv_calendar_header_dropdown_create(calendar)` creates a header that contains 2 drop-drown lists: one for the year and another for the month.
     69 
     70 
     71 ## Example
     72 
     73 ```eval_rst
     74 
     75 .. include:: ../../../examples/widgets/calendar/index.rst
     76 
     77 ```
     78 
     79 ## API
     80 
     81 ```eval_rst
     82 
     83 .. doxygenfile:: lv_calendar.h
     84   :project: lvgl
     85 
     86 ```