Skip to main content
Version: v2.4.0 (Current)

📅 Calendar

The Calendar widget provides a full-sized interactive grid for date selection. It is ideal for scheduling tasks, setting system clocks, or logging historical data events within your HMI.

⚙️ Properties (Props)​

The Calendar configuration is defined by the CalendarWidget interface. It uses a structured date object to manage the current selection.

PropertyTypeDescription
Selected DateDateValueThe currently highlighted date, consisting of year, month, and day.
Show HeaderbooleanToggles the visibility of the month and year navigation header.
Day NamesstringCustom labels for days of the week (e.g., "S, M, T, W, T, F, S").

📅 Date Structure​

When interacting with the Calendar via the Property Inspector or Lua, dates are handled using the following format:

  • Year: The full four-digit year (e.g., 2024).
  • Month: The month index (1-12).
  • Day: The day of the month (1-31).

🎨 Visual Customization​

The Calendar is composed of several sub-elements that can be styled in the Style Panel:

  • Main: The background container for the entire widget.
  • Items: The individual day cells.
  • Header: The navigation area at the top.
  • Special Dates: You can highlight specific days (like weekends or holidays) using a different background color.

⚡ Runtime API (Lua)​

The Calendar allows you to retrieve or set dates dynamically during simulation or on the target hardware.

-- Retrieve the currently selected date
local date = cal_system:get_selected_date()
print("Selected: " .. date.year .. "-" .. date.month .. "-" .. date.day)

-- Programmatically jump to a specific date
cal_system:set_today_date(2026, 3, 4)
cal_system:set_showed_date(2026, 3) -- Focus the view on March 2026

-- Highlight a series of dates (e.g., scheduled maintenance)
local highlighted = {
    {year=2026, month=3, day=15},
    {year=2026, month=3, day=20}
}
cal_system:set_highlighted_dates(highlighted)
MEMORY NOTE

The Calendar widget is feature-rich but occupies more screen real estate and memory than a simple Dropdown. For small displays, consider using multiple dropdowns for Year/Month/Day selection instead.

🚀 Next Steps​

  • Dropdown — A compact alternative for selecting dates or options.
  • Roller — An iOS-style scrolling selector for time and dates.
  • Logic and Events — Learn how to trigger system actions when a date is clicked.