Using the MonthCalendar Control

Two controls are available to enable the user to select the time and date. In this section, we’ll examine the MonthCalendar control; in the next section, we’ll look at the DateTimePicker control. The MonthCalendar control displays a calendar page that enables the user to select one or more dates. The user can scroll to additional months by using arrow buttons located at the top of the control.

The user selects a date from the MonthCalendar control by clicking the date displayed on the calendar page. By default, the user can select a range of dates. Initially, the user is allowed to select a range of up to seven dates. To change this behavior, use the MaxSelectionCount property, as shown in the following code, which restricts the user to selecting a single date at a time:

vacationCalendar.MaxSelectionCount = 1;

The following properties are used to get or set information about the currently selected dates in a MonthCalendar control:

SelectionStart A DateTime value that specifies the first selected date
SelectionRange A SelectionRange object that represents the dates selected in the control
SelectionEnd A DateTime value that specifies the last selected date

The SelectionRange class is used to model the relationship between the start and end dates. The SelectionRange class exposes the following two useful properties that shadow the properties available in the MonthCalendar class:

Start A DateTime value that represents the first date in the range
End A DateTime value that represents the last date in the range

If you’re setting a selection range for a MonthCalendar control, there are three constructors you can use to create a SelectionRange object. The most commonly used version of the constructor uses two DateTime values passed as parameters to define the range for the new SelectionRange object. The following code creates a SelectionRange object that contains a one-week time range. This object is then used to set the selected date range for a MonthCalendar control.

SelectionRange range = new SelectionRange(DateTime.Now,
                                          DateTime.Now.AddDays(6.0));
vacationCalendar.SelectionRange = range;

The second version of the SelectionRange constructor creates an empty object, as shown here:

SelectionRange range = new SelectionRange();

After you create a SelectionRange object with this constructor, you’ll need to use the Start and End properties to establish the endpoints for the range, as shown here:

SelectionRange range = new SelectionRange();
range.Start = DateTime.Now;
range.End = DateTime.Now.AddDays(3.0);
vacationCalendar.SelectionRange = range;

The third version of the constructor creates a new object by copying values from an existing SelectionRange object, as shown here:

SelectionRange defaultRange;

    

SelectionRange range = new SelectionRange(defaultRange);

The time period allowed for a MonthCalendar control is managed by two properties:

MinDate The earliest valid date for the control
MaxDate The latest valid date for the control

The following code restricts a MonthCalendar control to a two-week period. The user isn’t allowed to scroll to other months and isn’t allowed to select a date outside of the two-week period.

vacationCalendar.MinDate = DateTime.Now;
vacationCalendar.MaxDate = DateTime.Now.AddDays(14.0);

A single MonthCalendar control can display up to 12 months in a single grid. The dimensions of the calendar grid are set with the CalendarDimensions property, with the dimensions passed as a Size value, as shown here:

vacationCalendar.CalendarDimensions = new Size(2, 3);

This code creates a calendar that has two columns and three rows of months, as shown in Figure 15-7.

Figure 15-7.

A MonthCalendar control displaying a grid of six calendar months.

The MonthCalendar control can provide visual clues as to the current date. The ShowToday property is a Boolean value that specifies whether the date should be displayed at the bottom of the control. The default value for ShowToday is true. To prevent the current date from being displayed, set the property to false, as shown here:

vacationCalendar.ShowToday = false;

The ShowTodayCircle property specifies whether a circle is drawn around the current date. By default, this property is true, and the circle is drawn. To prevent the circle from being displayed, set this property to false, like this:

vacationCalendar.ShowTodayCircle = false;

By default, the date that’s shown in the control is obtained from the system clock. The TodayDate property can be used to set the date explicitly, as shown in this code, which sets the calendar’s date forward two days:

vacationCalendar.TodayDate = DateTime.Now.AddDays(2.0);

You can determine whether the date has been set explicitly with the TodayDateSet property, which returns true if the TodayDate property has been used to set the date, as shown here:

if(vacationCalendar.TodayDateSet)
{
    // Date has been explicitly set.
    
    

}

The FirstDayOfWeek property specifies the first day of the week displayed in the calendar, using one of these values from the Day enumeration:

Default
Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday

This property is normally set to Day.Default, which displays Sunday as the first day of the week. The following code changes the calendar to display Monday as the first day of the week:

vacationCalendar.FirstDayOfWeek = Day.Monday;

The ShowWeekNumbers method is used to specify whether week numbers are displayed in the calendar. By default, this property is false; to enable week numbers, set this property to true, as shown in this code:

vacationCalendar.ShowWeekNumbers = true;

Another visual clue that’s provided in the MonthCalendar control is the boldface rendering of special dates. Dates can be formatted in boldface on an individual basis, or they can be formatted in boldface on a repeating schedule so that the same dates appear in boldface for each month or are repeated for each year. A large number of methods and properties are dedicated to managing boldface dates. First let’s look at the methods and properties that work with nonrepeating boldface dates:

BoldedDates Property that specifies the current set of nonrepeating boldface dates
AddBoldedDate Method that adds a specific boldface date
RemoveBoldedDate Method that removes a specific boldface date
RemoveAllBoldedDates Method that removes all nonrepeating boldface dates

To set an initial set of boldface dates, assign an array of DateTime values to the BoldedDates property, as shown in the following code:

DateTime [] boldDates = new DateTime [] {
                                            DateTime.Now,
                                            DateTime.Now.AddDays(3.0),
                                            DateTime.Now.AddDays(6.0),
                                            DateTime.Now.AddDays(9.0)
                                        };
vacationCalendar.BoldedDates = boldDates;

You can also retrieve an array of DateTime values that represents the dates currently displayed in boldface, as shown here:

StringBuilder boldDateString = new StringBuilder();
foreach(DateTime day in vacationCalendar.BoldedDates)
{
    boldDateString.AppendFormat("{0}\n", day.ToShortDateString());
}
MessageBox.Show(boldDateString.ToString());

This code builds a string that contains the boldface dates from the vacationCalendar object and displays the result in a message box.

When assigning new values with the BoldedDates property, be aware that any new assignment to BoldedDates will overwrite the existing values. If you want to preserve existing boldface dates, the simplest approach is to use the AddBoldedDate method, as shown here:

vacationCalendar.AddBoldedDate(DateTime.Now.AddDays(1.0));

This example adds a new boldface date, without overwriting any of the existing boldface dates.

To remove a specific boldface date, use the RemoveBoldedDate method, as shown here:

vacationCalendar.RemoveBoldedDate(DateTime.Now.AddDays(1.0));

Alternatively, you can remove all nonrepeating boldface dates with the RemoveAllBoldedDates method:

vacationCalendar.RemoveAllBoldedDates();

After you update any of the boldface dates, you must call the UpdateBoldedDates method to ensure that the control draws the boldface dates properly, as shown here:

vacationCalendar.UpdateBoldedDates();

The CalendarMonth control also provides the following properties and methods used to manage dates that are repeated on a monthly or an annual basis:

MonthlyBoldedDates Property that specifies the set of repeating dates that are displayed in boldface on a monthly basis
AnnuallyBoldedDates Property that specifies the set of repeating dates that are displayed in boldface on an annual basis
AddMonthlyBoldedDate Method used to add a date to be displayed in boldface on a monthly basis
AddAnnuallyBoldedDate Method used to add a date to be displayed in boldface on an annual basis
RemoveMonthlyBoldedDate Method used to remove a specific date that’s displayed in boldface on a monthly basis
RemoveAnnuallyBoldedDate Method used to remove a specific date that’s displayed in boldface on an annual basis
RemoveAllMonthlyBoldedDates Method used to remove all dates displayed in boldface on a monthly basis
RemoveAllAnnuallyBoldedDates Method used to remove all dates displayed in boldface on an annual basis

These methods and properties work just like the nonrepeating boldface methods and properties discussed earlier except that these methods are used for dates that repeat on a monthly or an annual basis.

By default, the colors displayed by the MonthCalendar control are set to colors that fit in with the user’s color preferences. However, the colors can be customized according to your needs. The following properties affect the color of the control:

BackColor Specifies the color used for the background of the calendar page.
ForeColor Specifies the color used to display the numbers for the calendar dates.
TitleBackColor Specifies the background color used for the month caption. This color is also used for the text that heads the day columns.
TitleForeColor Specifies the foreground color used for the month caption.
TrailingForeColor Specifies the color used for dates that fall outside the displayed month.