XAML Calendar

A calendar control is used to create a visual calendar that lets users pick a date and fire an event on the selection of the date. This article demonstrates how to create and use a calendar control using XAML and C# in WPF.

Creating a Calendar

The Calendar element represents a calendar control in XAML as in the following:

<Calendar/>

The Calendar control is defined in the System.Windows.Controls namespace. When you drag and drop a Calendar control from the Toolbox to the page, the XAML code will look like the following code where you can see a Calendar XAML element has been added within the Grid element and its Width, Height, Name and VerticalAlignment and HorizontalAlignment attributes are set.

<Grid>
   <Calendar Height="170" HorizontalAlignment="Left" Margin="58,32,0,0"
      Name="calendar1" VerticalAlignment="Top" Width="180" />
</Grid>

The default view of the Calendar control looks as in Figure 1.


Figure 1

The Width and Height attributes of the Calendar element represent the width and the height of a Calendar. The Content attribute represents the text of a Calendar. The Name attribute represents the name of the control, that is a unique identifier of a control.

The code snippet in Listing 1 creates a Calendar control and sets the name, height and width properties of a Calendar control.

<Calendar Name=" MonthlyCalendar" Height="30" Width="100" >
</Calendar>

Listing 1

Display Modes

The DisplayMode property of the Calendar class represents the format of the display of a Calendar, that can be a month, year, or decade. Month is the default mode. Setting the DisplayMode to Year and Decade generates Figure 2 and Figure 3 respectively.


Figure 2


Figure 3

The Month view that is also the default view looks as in Figure 4.


Figure 4

If you use an example of the Decade and click on the year 2008 in Figure 3, you will get another Calendar format with all the months in the year 2008 and if you click on any month, you will eventually get the month view of the Calendar.

The following code snippet sets the DisplayMode property to Decade.

<Calendar DisplayMode="Decade">
</Calendar>

Selection Modes and Selection Dates

The SelectedDate property represents the currently selected date. If multiple dates selection is true, the SelectedDates property represents a collection of currently selected dates.

The SelectionMode of type CalendarSelectionMode enumeration represents the selection mode of calendar. Table 1 describes the CalendarSelectionMode enumeration and its members.

CalendarSelectionMode	Description
None	No selections are allowed.
SingleDate	Only a single date can be selected, either by setting SelectedDate or the first value in SelectedDates. AddRange cannot be used.
SingleRange	A single range of dates can be selected. Setting SelectedDate, adding a date individually to SelectedDates, or using AddRange will clear all previous values from SelectedDates.
MultipleRange	Multiple non-contiguous ranges of dates can be selected. Adding a date individually to SelectedDates or using AddRange will not clear SelectedDates. Setting SelectedDate will still clear SelectedDates, but additional dates or range can then be added. Adding a range that includes some dates that are already selected or overlaps with another range results in the union of the ranges and does not cause an exception.

The following code snippet sets the SelectionMode property to a single range.

<Calendar SelectionMode="SingleRange">
</Calendar>

BlackoutDates

The BlackoutDates property of the Calendar class represents a collection of dates that are not available for selection. All non-selection dates are marked by a cross. For example, say in the month of March of the year 2010, we would like to block the dates from Jan 1st to Jan 7th and then all Sundays and the final calendar should look as in Figure 5.


Figure 5

The following code snippet adds blackout dates to a Calendar.

<Calendar.BlackoutDates>
   <CalendarDateRange Start="3/1/2010" End="3/7/2010"/>
   <CalendarDateRange Start="3/8/2010" End="3/8/2010"/>
   <CalendarDateRange Start="3/15/2010" End="3/15/2010"/>
   <CalendarDateRange Start="3/22/2010" End="3/22/2010"/>
   <CalendarDateRange Start="3/29/2010" End="3/29/2010"/>
</Calendar.BlackoutDates>

We can do this by adding the code listed in Listing 2. As you can see from Listing 3, the BlackoutDates.Add method takes a CalendarDateRange object, that is a collection of two DateTime objects. The first date is the start date of the range and the second date is the end date of the date range.

private void SetBlackOutDates()
{
    MonthlyCalendar.BlackoutDates.Add(new CalendarDateRange(
        new DateTime(2010, 3, 1),
        new DateTime(2010, 3, 7)
        ));
    MonthlyCalendar.BlackoutDates.Add(new CalendarDateRange(
        new DateTime(2010, 3, 8),
        new DateTime(2010, 3, 8)
        ));
    MonthlyCalendar.BlackoutDates.Add(new CalendarDateRange(
      new DateTime(2010, 3, 15),
      new DateTime(2010, 3, 15)
      ));
    MonthlyCalendar.BlackoutDates.Add(new CalendarDateRange(
      new DateTime(2010, 3, 22),
      new DateTime(2010, 3, 22)
      ));
    MonthlyCalendar.BlackoutDates.Add(new CalendarDateRange(
      new DateTime(2010, 3, 29),
      new DateTime(2010, 3, 29)
      ));
}

Listing 2

DisplayDateStart and DisplayDateEnd

The Calendar control allows you to set the start and end display dates using the DisplayDateStart and DisplayDateEnd properties. If you see Figure 5 in the previous section, you may notice the March 2010 month calendar display starts with the March 01, 2010 date. But now, what if you want to display the dates for only the month of March 2010? We can use the DisplayStartDate and DisplayEndDate properties to control the start and end dates of a month.

DisplayDate property represents the current date to display.

The following code snippet sets the DisplayDate, DisplayDateStart and DisplayDateEnd attributes of the Calendar element in XAML.

<Calendar Name="MonthlyCalendar"
   SelectionMode="MultipleRange"
   DisplayDate="3/1/2010"
   DisplayDateStart="3/1/2010"
   DisplayDateEnd="3/31/2010"
/>

The code listed in Listing 3 makes sure the start date is March 01, 2010 and end date is March 31, 2010. The current selected date is March 05.

private void SetDisplayDates()
{
   MonthlyCalendar.DisplayDate = new DateTime(2010, 3, 5);
   MonthlyCalendar.DisplayDateStart = new DateTime(2010, 3, 1);
   MonthlyCalendar.DisplayDateEnd = new DateTime(2010, 3, 31);
}

Listing 3

The new calendar looks as in Figure 6.


Figure 6

FirstDayOfWeek and IsTodayHighlighted

By default, Sunday is the first day of the week. If you would like to change it, you use the FirstDayOfWeek property. The IsTodayHightlighted property is used to highlight today.

The following code snippet sets the FirstDayOfWeek to Tuesday and makes today highlighted.

<Calendar Name="MonthlyCalendar"
   SelectionMode="MultipleRange"
   DisplayDate="3/5/2010"
   DisplayDateStart="3/1/2010"
   DisplayDateEnd="3/31/2010"
   FirstDayOfWeek="Tuesday"
   IsTodayHighlighted="True"
   xmlns:sys="clr-namespace:System;assembly=mscorlib" Margin="15,39,88,19">

The following code snippet sets the FirstDayOfWeek to Tuesday and makes today highlighted in WPF.

MonthlyCalendar.FirstDayOfWeek = DayOfWeek.Tuesday;
MonthlyCalendar.IsTodayHighlighted = true;

The new calendar looks as in Figure 7, where you can see the start day of the week is Tuesday.


Figure 7

Selected Date and Selected Dates

The SelectedDate property represents the current selected date. If multiple date selection is true then the SelectedDates property represents all the selected dates in a Calendar. The following code snippet sets the SelectedDates in XAML at design-time.

<Calendar Name="MonthlyCalendar"
    SelectionMode="MultipleRange"
    DisplayDate="3/5/2010"
    DisplayDateStart="3/1/2010"
    DisplayDateEnd="3/31/2010"
    FirstDayOfWeek="Tuesday"
    IsTodayHighlighted="True"
    xmlns:sys="clr-namespace:System;assembly=mscorlib" Margin="15,39,88,19">

    <Calendar.SelectedDates>
        <sys:DateTime>3/5/2010</sys:DateTime>
        <sys:DateTime>3/15/2010</sys:DateTime>
        <sys:DateTime>3/25/2010</sys:DateTime>
     </Calendar.SelectedDates>

</Calendar>

The selected dates in a Calendar looks as in Figure 8 where you can see March 5th, 15th and 25th have a light blue background and represents the selected dates.


Figure 8

The following code snippet sets the SelectedDates property in WPF at run-time.

private void AddSelectedDates()
{
   MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 5));
   MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 15));
   MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 25));
}

Note: If you have set the selected dates to any of the blackout dates, you will see the parser in XAML will throw an error as in Figure 9.


Figure 9

Calendar Events

Besides the normal control events, the Calendar control has three events calendar related events. These events are the DisplayDateChanged, DisplayModeChanged and SelectedDatesChanged. The DisplayDateChanged event is fired where the DisplayDate property is changed. The DisplayModeChanged event is fired when the DisplayMode property is changed. The SelectedDatesChanged event is fired when the SelectedDate or SelectedDates properties are changed. The following code snippet sets these three events attributes.

<Calendar SelectionMode="SingleRange"
   Name="MonthlyCalendar"
   SelectedDatesChanged="MonthlyCalendar_SelectedDatesChanged"
   DisplayDateChanged="MonthlyCalendar_DisplayDateChanged"
   DisplayModeChanged="MonthlyCalendar_DisplayModeChanged"
   HorizontalAlignment="Left"
   VerticalAlignment="Top"
   Margin="10,10,0,0">
</Calendar>

The code behind for these events look as in Listing 4.

private void MonthlyCalendar_SelectedDatesChanged(object sender,
    SelectionChangedEventArgs e)
{
}
private void MonthlyCalendar_DisplayDateChanged(object sender,
    CalendarDateChangedEventArgs e)
{
}
private void MonthlyCalendar_DisplayModeChanged(object sender,
    CalendarModeChangedEventArgs e)
{
}

Listing 4

Normally, on a date selection, you may want to capture that event and know what the current selected date is. Now how about we add a TextBox control to the page and on the date selection, we will set the text of the TextBox to the currently selected date.

We add the following code to the XAML just below the Calendar control.

<TextBox Width="200" Height="30"
   VerticalAlignment="Bottom"
   HorizontalAlignment="Left"
   Margin="10,10,10,10"
   x:Name="SelectedDateTextBox">
</TextBox>

On the SelectedDateChanged event handler, we set the TextBox.Text property to the SelectedDate property of the Calendar control as you can see from the code in Listing 5.

private void MonthlyCalendar_SelectedDatesChanged(object sender,
    SelectionChangedEventArgs e)
{
    SelectedDateTextBox.Text = MonthlyCalendar.SelectedDate.ToString();
}

Listing 5

Now when you run the application, you will see the output that looks as in Figure 10. When you select a date in the Calendar, it will be displayed in the TextBox.


Figure 10

Formatting a Calendar

How about we create a Calendar control with a border formatting, background and foreground of the Calendar?

The BorderBrush property of the Calendar sets a brush to draw the border of a Calendar. You may use any brush to fill the border. The following code snippet uses a linear gradient brush to draw the border with a combination of the colors Red and Blue.

<Calendar.BorderBrush>
   <LinearGradientBrush StartPoint="0,0" EndPoint="1,1" >
      <GradientStop Color="Blue" Offset="0" />
      <GradientStop Color="Red" Offset="1.0" />
   </LinearGradientBrush>
</Calendar.BorderBrush>

The Background and Foreground properties of the Calendar set the background and foreground colors of a Calendar. You may use any brush to fill the border. The following code snippet uses linear gradient brushes to draw the background and foreground of a Calendar.

<Calendar.Background>
    <LinearGradientBrush StartPoint="0,0" EndPoint="1,1" >
        <GradientStop Color="Blue" Offset="0.1" />
        <GradientStop Color="Orange" Offset="0.25" />
        <GradientStop Color="Green" Offset="0.75" />
        <GradientStop Color="Red" Offset="1.0" />
    </LinearGradientBrush>
</Calendar.Background>
<Calendar.Foreground>
    <LinearGradientBrush StartPoint="0,0" EndPoint="1,1" >
        <GradientStop Color="Black" Offset="0.25" />
        <GradientStop Color="Green" Offset="1.0" />
    </LinearGradientBrush>
</Calendar.Foreground>

The new Calendar looks as in Figure 11.


Figure 11

Setting Image as Background of a Calendar

To set an image as the background of a Calendar, we can set an image as the Background of the Calendar. The following code snippet sets the background of a Calendar to an image. The code also sets the opacity of the image.

<Calendar.Background>
   <ImageBrush ImageSource="Garden.jpg" Opacity="0.3"/>
</Calendar.Background>

The new output looks as in Figure 12.


Figure 12

Creating a Calendar Dynamically

The code listed in Listing 6 creates a Calendar control programmatically. First, it creates a Calendar object and sets its DisplayMode and SelectedMode and other properties and later the Calendar is added to the LayoutRoot.

private void CreateDynamicCalendar()
{
    Calendar MonthlyCalendar = new Calendar();
    MonthlyCalendar.Name = "MonthlyCalendar";
    MonthlyCalendar.Width = 300;
    MonthlyCalendar.Height = 400;
    MonthlyCalendar.Background = Brushes.LightBlue;
    MonthlyCalendar.DisplayMode = CalendarMode.Month;
    MonthlyCalendar.SelectionMode = CalendarSelectionMode.SingleRange;
    MonthlyCalendar.DisplayDateStart = new DateTime(2010, 3, 1);
    MonthlyCalendar.DisplayDateEnd = new DateTime(2010, 3, 31);
    MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 5));
    MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 15));
    MonthlyCalendar.SelectedDates.Add(new DateTime(2010, 3, 25));

    MonthlyCalendar.FirstDayOfWeek = DayOfWeek.Monday;
    MonthlyCalendar.IsTodayHighlighted = true;

    LayoutRoot.Children.Add(MonthlyCalendar);
}

Listing 6

Summary

In this article, I discussed the calendar control using XAML and C#. We also saw how to set display modes, selection modes, blackout dates, selected dates, border, background and foreground properties. After that, we saw you to set an image as the background of a Calendar. In the end of this article, we saw how to create a Calendar dynamically.