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 style

    • pressed date: drawn with LV_STATE_PRESSED style

    • today: drawn with LV_STATE_FOCUSED style

    • highlighted 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.

Keys

No Keys are processed by the object type.

Learn more about Keys.

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

No examples yet.

API

Typedefs

typedef uint8_t lv_calendar_part_t

Enums

enum [anonymous]

Calendar parts

Values:

enumerator LV_CALENDAR_PART_BG

Background and "normal" date numbers style

enumerator LV_CALENDAR_PART_HEADER
enumerator LV_CALENDAR_PART_DAY_NAMES

Calendar header style

enumerator LV_CALENDAR_PART_DATE

Day name style

Functions

lv_obj_t *lv_calendar_create(lv_obj_t *par, const lv_obj_t *copy)

Create a calendar objects

Return

pointer to the created calendar

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

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 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

Return

return pointer to an lv_calendar_date_t variable containing the date of today.

Parameters
  • calendar: pointer to a calendar object

lv_calendar_date_t *lv_calendar_get_showed_date(const lv_obj_t *calendar)

Get the currently showed

Return

pointer to an lv_calendar_date_t variable containing the date is being shown.

Parameters
  • calendar: pointer to a calendar object

lv_calendar_date_t *lv_calendar_get_pressed_date(const lv_obj_t *calendar)

Get the the pressed date.

Return

pointer to an lv_calendar_date_t variable containing the pressed date. NULL if not date pressed (e.g. the header)

Parameters
  • calendar: pointer to a calendar object

lv_calendar_date_t *lv_calendar_get_highlighted_dates(const lv_obj_t *calendar)

Get the the highlighted dates

Return

pointer to an lv_calendar_date_t array containing the dates.

Parameters
  • calendar: pointer to a calendar object

uint16_t lv_calendar_get_highlighted_dates_num(const lv_obj_t *calendar)

Get the number of the highlighted dates

Return

number of highlighted days

Parameters
  • calendar: pointer to a calendar object

const char **lv_calendar_get_day_names(const lv_obj_t *calendar)

Get the name of the days

Return

pointer to the array of day names

Parameters
  • calendar: pointer to a calendar object

const char **lv_calendar_get_month_names(const lv_obj_t *calendar)

Get the name of the month

Return

pointer to the array of month names

Parameters
  • calendar: pointer to a calendar object

struct lv_calendar_date_t
#include <lv_calendar.h>

Represents a date on the calendar object (platform-agnostic).

Public Members

uint16_t year
int8_t month
int8_t day
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