Overview of the New Calendar for Windows Forms

Berkunath A
September 15, 2021 UPDATED

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.

Calendar component

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:

Syncfusion.SfInput.WinForms
Syncfusion.Core.WinForms

You can find the required assemblies in the following location:

$ Installed Location:\Syncfusion\Essential Studio\$Version #\precompiledassemblies\$Version#\[TargetFramework]

E.g.: C:\Program Files (x86)\Syncfusion\Essential Studio\16.1.0.24\precompiledassemblies\16.1.0.24\4.6

Add the namespace Syncfusion.WinForms.Input.

using Syncfusion.WinForms.Input;

3. Add the SfCalendar component to your form:

SfCalendar calendar = new SfCalendar();
this.Controls.Add(calendar);

Now, a simple calendar control is ready to use. Let’s add more stuff to it.

Date Range

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

Date Range

Date selection

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 as true.

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.

Multiple selection

Special dates

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
SpecialDates.Add(specialDate1);

calendar.SpecialDates = SpecialDates;

Calendar with Special Dates

Blackout 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

Globalization

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

Cell customization

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

   if(args.IsTrailingDate)
   {
    // 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

Appearance 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

Wrapping up

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.

Learn more

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.