This blog post is an overview of the calendar control for Windows Forms and important features you should know.
The calendar control allows users to select a date interactively as well as programmatically. It has all the functionalities of the standard Syncfusion Windows Forms month calendar, plus advanced functionalities such as multiple selection, UI customization, and more.
Month calendar versus calendar
If you are already using the Syncfusion month calendar, you may wonder why you need this new calendar. Here are some of the advantages of the new one over the existing control:
- Special dates
- Blackout dates
- Cell customization
- Appearance customization
- Developer-friendly API structure
The purpose of each of these features is explained in this blog post. We recommend you use this control for new projects as we will be adding new features to this control. We will only be providing bug fixes for the older month calendar control from now on.
Getting started with the new calendar control
The new calendar control can be configured in Windows Forms applications by following these instructions:
- Add the following required assemblies in your project:
You can find the required assemblies in the following
$ Installed Location:\Syncfusion\Essential Studio\$Version
E.g.: C:\Program Files
- Add the namespace Syncfusion.WinForms.Input.
3. Add the SfCalendar component to your form:
SfCalendar calendar = new SfCalendar();
Now, a simple calendar control is ready to use. Let’s add more stuff to it.
Sometimes users expect to set a date within a specific range. The calendar control allows this kind of constraint for minimum and maximum dates. After setting minimum and maximum dates, the calendar will display the dates within the specified range. Other dates will not be displayed.
SfCalendar calendar = new SfCalendar();
calendar.MinDate = new DateTime(2018, 2, 27);
calendar.MaxDate = new DateTime(2018, 4, 05);
The calendar component allows users to select one or more dates. By default, it allows single selection. Multiple date selection can be enabled by setting AllowMultipleSelection
calendar.AllowMultipleSelection = true;
The calendar allows selection by mouse, keyboard, and touch interactions to make applications available to a wide variety of users. Users may want to select multiple, separate dates, or sometimes multiple dates in a single range. The calendar component provides easy selection for both cases.
To select separate dates, hold Ctrl while selecting the required dates with the mouse.
To select a range, hold Shift and use the arrow keys, Home, or End.
The calendar component provides options to mark special dates with details. It also provides options to customize the appearance of special dates in a unique manner. Special dates can be added to the calendar simply by adding the date with customization details, as in the following code samples.
List SpecialDates = new List();
SpecialDate specialDate1 = new SpecialDate();
specialDate1.BackColor = System.Drawing.Color.White;
specialDate1.ForeColor = System.Drawing.Color.Magenta;
specialDate1.Image = Properties.Resources.Icon_Christmas_day;
specialDate1.Description = "Christmas";
specialDate1.ImageAlign = System.Drawing.ContentAlignment.MiddleCenter;
specialDate1.IsDateVisible = false;
specialDate1.TextAlign = System.Drawing.ContentAlignment.MiddleCenter;
specialDate1.TextImageRelation = System.Windows.Forms.TextImageRelation.TextBeforeImage;
specialDate1.Value = new System.DateTime(2018, 12, 25, 0, 0, 0, 0);
// Here we can add the collection of special dates with required settings
calendar.SpecialDates = SpecialDates;
Calendar with Special Dates
Every calendar control provides options for users to restrict the selectable dates within a range. Our new calendar control also provides date range support to select dates within a range, but sometimes users want to restrict the selection of certain dates that fall within the minimum and maximum date range. The calendar manages this scenario by providing blackout dates, which allows dates that should not be available for selection to be easily added.
List blackoutDates = new List();
// Here we can add the collection of blackout dates
blackoutDates.Add(new System.DateTime(2018, 2, 11, 0, 0, 0, 0));
blackoutDates.Add(new System.DateTime(2018, 2, 12, 0, 0, 0, 0));
blackoutDates.Add(new System.DateTime(2018, 2, 13, 0, 0, 0, 0));
calendar.BlackoutDates = blackoutDates;
Calendar with Blackout Dates
The calendar control provides globalization support to help when designing and developing a world-ready application with localized interfaces and regional data for wider audiences. Date information in the calendar can be displayed based on the user-specified culture by simply setting Culture
as in the following code sample.
calendar.Culture = new CultureInfo("zh-CN");
Calendar with zh-CN culture applied
The calendar component provides special date support to customize the appearance of special dates that are predefined. However, when users utilize cell customization on demand with the DrawCell
event, they can customize the appearance of special dates on demand without having to define their list of dates in advance. Notice that the DrawCellEventArgs
has a Bounds
property. This is where you can draw a cell with whatever you want in a special date cell by handling the DrawCellEvent
. The following code sample illustrates how to customize the date cell on demand.
this.sfCalendar1.DrawCell += SfCalendar1_DrawCell;
void SfCalendar1_DrawCell(SfCalendar sender, Syncfusion.WinForms.Input.Events.DrawCellEventArgs args)
// Customize the cell appearance using options from DrawCellEventArgs
args.ForeColor = Color.DarkGray;
else if(args.Value.Value == (new System.DateTime(2018, 2, 10, 0, 0, 0, 0)))
args.Handled = true;
// Customize the cell appearance by your own drawing using Graphics and Bounds of cell from DrawCellEventArgs
Calendar with cell customization
The default UI of the calendar control can be customized. It provides flexible APIs for changing the appearance of each element of the calendar. The following code example illustrates how to customize the calendar.
SfCalendar calendar = new SfCalendar();
calendar.Style.BorderColor = ColorTranslator.FromHtml("#FFDFDFDF");
calendar.Style.Cell.CellBackColor = ColorTranslator.FromHtml("#FF555555");
calendar.Style.Cell.CellForeColor = ColorTranslator.FromHtml("#FFFFFFFF");
calendar.Style.Cell.SelectedCellBorderColor = ColorTranslator.FromHtml("#0078d7");
calendar.Style.Cell.SelectedCellBackColor = ColorTranslator.FromHtml("#FF0078D7");
calendar.Style.Cell.SelectedCellForeColor = ColorTranslator.FromHtml("#FFFFFFFF");
calendar.Style.Cell.TrailingCellBackColor = ColorTranslator.FromHtml("#FF555555");
calendar.Style.Header.BackColor = ColorTranslator.FromHtml("#FF555555");
calendar.Style.Header.ForeColor = ColorTranslator.FromHtml("#FFDFDFDF");
calendar.Style.Header.HoverForeColor = ColorTranslator.FromHtml("#FFFFFFFF");
calendar.Style.Header.DayNamesForeColor = ColorTranslator.FromHtml("#FFFFFFFF");
calendar.Style.Header.DayNamesBackColor = ColorTranslator.FromHtml("#FF555555");
calendar.Style.Header.NavigationButtonForeColor = ColorTranslator.FromHtml("#FFDFDFDF");
calendar.Style.Header.NavigationButtonHoverForeColor = ColorTranslator.FromHtml("#FFFFFFFF");
Calendar with customized appearance
We hope the new calendar component provides what users demand of a calendar control, especially through the various features that will help cover a wider audience: globalization, easy navigation, blackout dates, and special dates with full-fledged customization.
Here we just covered the essential features of the calendar. For more information and details about other advanced topics, please refer to our documentation
where you will see code samples for features not covered here, like the restriction of views, showing week numbers, and numbering weeks in views.
If you’re already a Syncfusion user, you can download the product setup here
. If you’re not yet a Syncfusion user, you can download a free, 30-day trial here
Feel free to share your feedback in the comments below. You can also contact us through our support forum
. We are happy to assist you!
Sample code for the features explained in this blog post can be downloaded here: Calendar Samples