wxCalendarCtrl(3)

📦

version 29.0.6 · 3 versions

💖 wxCalendarCtrl 💖 — the manual, but make it cute

okay bestie, gather round, because we're talking about wxCalendarCtrl from Erlang's wxWidgets bindings, and she is literally the calendar control that lets the user pick a date. 🗓️✨

🌸 DESCRIPTION 🌸

So the user can move the current selection around with the keyboard (yes, keys, we love a keyboard moment), and then actually select the date — which fires off an EVT_CALENDAR event — by pressing Return or double clicking it. boom. date picked. iconic behavior. 🫶

Now, the generic calendar has advanced possibilities for customizing its display, which we're about to get into below. and if you want those same possibilities on every platform? use wxGenericCalendarCtrl instead of wxCalendarCtrl. no cap. 💅

All the global settings (like colours and fonts, the whole aesthetic) can of course be changed. but ALSO — plot twist — the display style for each individual day in the month can be set independently using the wxCalendarDateAttr class. one day at a time, bestie. 🎀

An item that has no custom attributes gets drawn with the default colours and font and with no border. but the moment you set custom attributes with setAttr/3, you can modify its appearance. the move is: create a custom attribute object, then set it for the day you want to be displayed specially. ⚠️ heads up though — the control takes ownership of the pointer, i.e. it will delete it itself. so don't you go deleting it too, that's a double-free and we don't do that. 😭

A day can be marked as being a holiday — even if it's not recognized as one by wx_datetime() — using the wxCalendarDateAttr:setHoliday/2 method. ✨

And because the attributes are specified per day, they may change when the month is changed. so you'll often want to update them inside an EVT_CALENDAR_PAGE_CHANGED event handler. keep up, keep up. 🔥

If neither the wxCAL_SUNDAY_FIRST nor the wxCAL_MONDAY_FIRST style is given, then the first day of the week is determined from the operating system's settings, if possible. and the native wxGTK calendar? it chooses the first weekday based on locale, and these styles have no effect on it. periodt. 💀

🦋 Styles 🦋

This class supports the following styles:

wxCAL_SUNDAY_FIRST — Show Sunday as the first day in the week (not in wxGTK)
wxCAL_MONDAY_FIRST — Show Monday as the first day in the week (not in wxGTK)
wxCAL_SHOW_HOLIDAYS — Highlight holidays in the calendar (only generic)
wxCAL_NO_YEAR_CHANGE — Disable the year changing (deprecated, only generic)
wxCAL_NO_MONTH_CHANGE — Disable the month (and, implicitly, the year) changing
wxCAL_SHOW_SURROUNDING_WEEKS — Show the neighbouring weeks in the previous and next months (only generic, always on for the native controls)
wxCAL_SEQUENTIAL_MONTH_SELECTION — Use alternative, more compact, style for the month and year selection controls. (only generic)
wxCAL_SHOW_WEEK_NUMBERS — Show week numbers on the left side of the calendar. (not in generic)

👀 See also:

Examples
wxCalendarDateAttr
wxCalendarEvent
wxDatePickerCtrl

This class is derived, and can use functions, from:

wxControl
wxWindow
wxEvtHandler

wxWidgets docs: wxCalendarCtrl

🎉 Events 🎉

Event types emitted from this class:

calendar_sel_changed
calendar_weekday_clicked

🌈 DATA TYPES 🌈

wxCalendarCtrl() :: wx:wx_object().

to be continued, bestie — part 2 is on the way 🧚

✨ FUNCTIONS ✨

Okay bestie, this is where the calendar control actually does stuff. Every function, every type, every little when clause — we're keeping it all. Let's go. 💅

✨ create

create(This, Parent, Id, [Option]) -> boolean()
                       when
                           This :: wxCalendarCtrl(),
                           Parent :: wxWindow:wxWindow(),
                           Id :: integer(),
                           Option ::
                               {date, wx:wx_datetime()} |
                               {pos, {X :: integer(), Y :: integer()}} |
                               {size, {W :: integer(), H :: integer()}} |
                               {style, integer()}.

Creates the control. ✨

See wxWindow:new/3 for the meaning of the parameters and the control overview for the possible styles. 👑

✨ destroy

destroy(This :: wxCalendarCtrl()) -> ok.

Destroys the object.

✨ enableHolidayDisplay

enableHolidayDisplay(This, [Option]) -> ok
                                     when
                                         This :: wxCalendarCtrl(),
                                         Option :: {display, boolean()}.

This function should be used instead of changing wxCAL_SHOW_HOLIDAYS style bit directly.

It enables or disables the special highlighting of the holidays. 🎀

✨ enableMonthChange

enableMonthChange(This, [Option]) -> boolean()
                                  when
                                      This :: wxCalendarCtrl(),
                                      Option :: {enable, boolean()}.

This function should be used instead of changing wxCAL_NO_MONTH_CHANGE style bit.

It allows or disallows the user to change the month interactively. Note that if the month cannot be changed, the year cannot be changed neither.

Return: true if the value of this option really changed or false if it was already set to the requested value.

✨ enableYearChange

enableYearChange(This, [Option]) -> ok
                                 when
                                     This :: wxCalendarCtrl(),
                                     Option :: {enable, boolean()}.

Deprecated: wxCalendarCtrl:enableYearChange/2 is deprecated; not available in wxWidgets-2.9 and later

Deprecated:

This function should be used instead of changing wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the user to change the year interactively. Only in generic wxCalendarCtrl.

✨ getAttr

getAttr(This, Day) -> wxCalendarDateAttr:wxCalendarDateAttr()
                        when This :: wxCalendarCtrl(), Day :: integer().

Returns the attribute for the given date (should be in the range 1...31).

The returned pointer may be NULL. Only in generic wxCalendarCtrl.

✨ getDate

getDate(This) -> wx:wx_datetime() when This :: wxCalendarCtrl().

Gets the currently selected date. 🗓️

✨ getHeaderColourBg

getHeaderColourBg(This) -> wx:wx_colour4()
                                  when This :: wxCalendarCtrl().

Gets the background colour of the header part of the calendar window.

This method is currently only implemented in generic wxCalendarCtrl and always returns wxNullColour in the native versions.

See: setHeaderColours/3

✨ getHeaderColourFg

getHeaderColourFg(This) -> wx:wx_colour4()
                                  when This :: wxCalendarCtrl().

Gets the foreground colour of the header part of the calendar window.

This method is currently only implemented in generic wxCalendarCtrl and always returns wxNullColour in the native versions.

See: setHeaderColours/3

✨ getHighlightColourBg

getHighlightColourBg(This) -> wx:wx_colour4()
                                     when This :: wxCalendarCtrl().

Gets the background highlight colour.

Only in generic wxCalendarCtrl.

This method is currently only implemented in generic wxCalendarCtrl and always returns wxNullColour in the native versions.

See: setHighlightColours/3

✨ getHighlightColourFg

getHighlightColourFg(This) -> wx:wx_colour4()
                                     when This :: wxCalendarCtrl().

Gets the foreground highlight colour.

Only in generic wxCalendarCtrl.

This method is currently only implemented in generic wxCalendarCtrl and always returns wxNullColour in the native versions.

See: setHighlightColours/3

✨ getHolidayColourBg

getHolidayColourBg(This) -> wx:wx_colour4()
                                   when This :: wxCalendarCtrl().

Return the background colour currently used for holiday highlighting.

Only useful with generic wxCalendarCtrl as native versions currently don't support holidays display at all and always return wxNullColour.

See: setHolidayColours/3

✨ getHolidayColourFg

getHolidayColourFg(This) -> wx:wx_colour4()
                                   when This :: wxCalendarCtrl().

Return the foreground colour currently used for holiday highlighting.

Only useful with generic wxCalendarCtrl as native versions currently don't support holidays display at all and always return wxNullColour.

See: setHolidayColours/3

✨ hitTest

hitTest(This, Pos) -> Result
                        when
                            Result ::
                                {Res :: wx:wx_enum(),
                                 Date :: wx:wx_datetime(),
                                 Wd :: wx:wx_enum()},
                            This :: wxCalendarCtrl(),
                            Pos :: {X :: integer(), Y :: integer()}.

Returns one of wxCalendarHitTestResult constants and fills either date or wd pointer with the corresponding value depending on the hit test code.

Not implemented in wxGTK currently.

✨ new()

new() -> wxCalendarCtrl().

Default constructor.

✨ new(Parent, Id, [Option])

new(Parent, Id, [Option]) -> wxCalendarCtrl()
                    when
                        Parent :: wxWindow:wxWindow(),
                        Id :: integer(),
                        Option ::
                            {date, wx:wx_datetime()} |
                            {pos, {X :: integer(), Y :: integer()}} |
                            {size, {W :: integer(), H :: integer()}} |
                            {style, integer()}.

Does the same as create/4 method.

✨ resetAttr

resetAttr(This, Day) -> ok
                          when This :: wxCalendarCtrl(), Day :: integer().

Clears any attributes associated with the given day (in the range 1...31).

Only in generic wxCalendarCtrl.

✨ setAttr

setAttr(This, Day, Attr) -> ok
                        when
                            This :: wxCalendarCtrl(),
                            Day :: integer(),
                            Attr :: wxCalendarDateAttr:wxCalendarDateAttr().

Associates the attribute with the specified date (in the range 1...31).

If the pointer is NULL, the items attribute is cleared. Only in generic wxCalendarCtrl.

✨ setDate

setDate(This, Date) -> boolean()
                        when This :: wxCalendarCtrl(), Date ::
       wx:wx_datetime().

Sets the current date.

The date parameter must be valid and in the currently valid range as set by SetDateRange() (not implemented in wx), otherwise the current date is not changed and the function returns false and, additionally, triggers an assertion failure if the date is invalid.

Heads up, bestie: invalid date = no change + false + assertion failure. The math is mathing. 😭

✨ setHeaderColours

setHeaderColours(This, ColFg, ColBg) -> ok
                                 when
                                     This :: wxCalendarCtrl(),
                                     ColFg :: wx:wx_colour(),
                                     ColBg :: wx:wx_colour().

Set the colours used for painting the weekdays at the top of the control.

This method is currently only implemented in generic wxCalendarCtrl and does nothing in the native versions.

✨ setHighlightColours

setHighlightColours(This, ColFg, ColBg) -> ok
                                    when
                                        This :: wxCalendarCtrl(),
                                        ColFg :: wx:wx_colour(),
                                        ColBg :: wx:wx_colour().

Set the colours to be used for highlighting the currently selected date.

This method is currently only implemented in generic wxCalendarCtrl and does nothing in the native versions.

✨ setHoliday

setHoliday(This, Day) -> ok
                           when This :: wxCalendarCtrl(), Day :: integer().

Marks the specified day as being a holiday in the current month.

This method is only implemented in the generic version of the control and does nothing in the native ones.

✨ setHolidayColours

setHolidayColours(This, ColFg, ColBg) -> ok
                                  when
                                      This :: wxCalendarCtrl(),
                                      ColFg :: wx:wx_colour(),
                                      ColBg :: wx:wx_colour().

Sets the colours to be used for the holidays highlighting.

This method is only implemented in the generic version of the control and does nothing in the native ones. It should also only be called if the window style includes wxCAL_SHOW_HOLIDAYS flag or enableHolidayDisplay/2 had been called.

And that's the whole calendar control, bestie. Periodt. 💖

This page came from Ericsson AB, wx 2.6, and it's the wxCalendarCtrl(3) manual. Slay. 🫶

📦 where this page comes from

ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms