WinCalendar control (2024)

Collapse All

Language Filter: All

The WinCalendar class represents an extensible and themable calendar control for Windows Forms which can display one or many months. It supports regional settings, as well as both the Windows XP and classic Windows themes, and can adapt to the current regional settings and Windows theme. The WinCalendar control can contain any of the Xceed editors as well as any other .NET control.

Months

When the WinCalendar control is dropped on a form or instantiated via code, by default it displays the current month. Setting the WinCalendar's EnableMultipleMonths property to true (default) allows more than one month to be displayed in the calendar when the calendar is expanded. The first month that is displayed in a multi-month calendar is determined by the value of the FirstMonth property (by default, the current month), while the maximum and minimum months are determined by the MaxValue and MinValue properties. Navigation within the calendar, regardless of the number of months displayed, is limited between the minimum and the maximum months.

By setting the ShowPreviewDays property to true (default), the first and last month displayed in the calendar is modified to include greyed-out "preview days". This is illustrated in the image below, where the last few days of September 2004 are displayed before the first day of October 2004, and the first few days of February 2005 are displayed after the last day of January 2005. Setting ShowPreviewDays to false prevents preview days from being displayed.

Current and selected dates

The WinCalendar control differentiates between the present date (Today), the selected date, and the current date. "Today" is always the present date (DateTime.Today) and is represented by a light highlight (light blue in the image below). The SelectedDate is the day that is selected by the user (or via code) and is represented by a dark highlight (dark blue in the image). The CurrentDate is the day that currently has the focus and is represented by the focus rectangle. By default, both the CurrentDate and the SelectedDate are set to the present date (Today). If no date is currently selected, SelectedDate will be set to NullDate (by default, DateTime.MinValue).

When navigating through the WinCalendar with the keyboard, the CurrentDate will be moved around. When the spacebar is pressed, the day that is the CurrentDate will also become the SelectedDate. The SelectedDate can also be set by clicking on a day with the mouse.

The following table provides a list of the keys which can be used to navigate within the WinCalendar control:

By default, the present date ("Today") is always highlighted. To remove the highlight, the HighlightToday property must be set to false.

The foreground and background colors of the current and selected dates can modified via the TodayForeColor, TodayBackColor, SelectionForeColor, and SelectionBackColor properties ONLY when using the WindowsClassic UIStyle. These colors cannot be modified when using the WindowsXP, System (when the OS is using an XP theme) or ResourceAssembly UIStyles.

Today and None buttons

When the WinCalendar control is dropped on a form in the designer or instantiated in code using the constructor with 2 boolean parameters, it will contain 2 buttons. The "Today" button is accessible via the TodayButton property and is used to bring the current date into view and set the current date as the SelectedDate. The "None" button is accessible via the NoneButton property and is used to deselect the SelectedDate. Any WinButton control can be used as the "Today" or "None" button by assigning it to the TodayButton or NoneButton properties.

To remove a WinButton's association as the "Today" or "None" buttons, the TodayButton and NoneButton properties must be set to null (Nothing in Visual Basic). Setting the TodayButton and NoneButton properties to null (Nothing in Visual Basic) will not remove the buttons from the calendar.

To remove the "Today" and "None" buttons that are located within the WinCalendar control, they must be removed from the WinCalendar's Controls collection (or selected and deleted in the designer).

VB.NET	Copy Code
WinCalendar1.Controls.Remove( WinCalendar1.TodayButton ) WinCalendar1.Controls.Remove( WinCalendar1.NoneButton ) ' Remove the calendar's bottom margin which contained the "Today" and "None" buttons WinCalendar1.Margins = New Margins( 1 )

C#	Copy Code
winCalendar1.Controls.Remove( winCalendar1.TodayButton ); winCalendar1.Controls.Remove( winCalendar1.NoneButton ); // Remove the calendar's bottom margin which contained the "Today" and "None" buttons winCalendar1.Margins = new Margins( 1 );