The MonthCalendar control displays a calendar that allows the user to select a range of dates. This calendar is similar to the one that the DateTimePicker control displays when its ShowUpDown property is False and you click the control’s drop-down arrow. See the section “DateTimePicker” earlier in this appendix for more information on that control.
Figure G-12 shows a dialog box that uses the MonthCalendar control. The right and left arrows at the top of the calendar let you move through months. If you click the month, the control displays a pop-up menu listing the months so that you can quickly select one. If you click the year, the control displays small up and down arrows that you can use to change the year. When you have found the month and year you want, click a date to select it.
Figure G-12: The MonthCalendar control lets the user select dates or a range of dates.
If you get lost scrolling through the calendar’s months, you can click the Today entry at the bottom of the calendar to jump back to the current date. You can also right-click the calendar and select the Go to today command.
The MonthCalendar control’s MinDate and MaxDate properties determine the first and last dates that the control will let the user select.
The DateTimePicker control is designed to let the user select a single date. The MonthCalendar control is a bit more powerful. For example, this control can allow the user to select a range of dates by clicking and dragging across the calendar. The program can use the control’s SelectionRange, SelectionStart, and SelectionEnd properties to see what dates the user has selected.
The following table describes the control’s most useful properties for controlling its more advanced features.
Property | Purpose |
---|---|
AnnuallyBoldedDates | An array that specifies dates that should be bolded every year. For example, you can bold April 1 for every year displayed. |
BoldedDates | An array that specifies specific dates that should be displayed in bold. |
CalendarDimensions | Sets the number of columns and rows of months the control displays. Figure G-13 shows a MonthCalendar control with CalendarDimensions = 3, 2 (three columns and two rows). |
FirstDayOfWeek | Sets the day of the week shown in the leftmost column of each month. Figure G-13 uses the default value Sunday. |
MaxDate | The last date the user is allowed to select. |
MaxSelectionCount | The maximum number of days the user can select. |
MinDate | The first date the user is allowed to select. |
MonthlyBoldedDates | An array that specifies dates that should be bolded every month. For example, you can bold the 13th of every month displayed. |
SelectionEnd | A DateTime object representing the control’s last selected date. |
SelectionRange | A SelectionRange object representing the control’s selected range of dates. |
SelectionStart | A DateTime object representing the control’s first selected date. |
ShowToday | Determines whether the control displays today’s date at the bottom. |
ShowTodayCircle | Determines whether the control circles today’s date (January 28, 2007 in Figure G-13). (Although on this system at least the date is circled with a rectangle.) |
ShowWeekNumbers | Determines whether the control displays the number of each week in the year to the left of each week. |
SingleMonthSize | Returns the minimum size needed to display a single month. |
TodayDate | Determines the date displayed as today’s date (January 28, 2007 in Figure G-13). |
TodayDateSet | Boolean that indicates whether the control’s TodayDate property has been explicitly set. |
Figure G-13: The MonthCalendar control can display more than one month at a time.
The TodayDate property has an annoying side effect. If you set this value at design time and then set it back to the current day’s date, the control’s TodayDateSet property still returns True, indicating that you have set the TodayDate property. To clear TodayDate so that TodayDateSet returns False, right-click the name (not the value) of the TodayDate property in the Properties window and select Reset.
The following code demonstrates several of these properties. It begins by initializing a DateTime variable to the first date allowed by the control. It checks the variable’s day of the week and adds a number of days to move the variable to the following Monday. The code then builds an array of DateTime objects holding all of the Mondays between the first and last dates allowed by the MonthCalendar control and sets the control’s BoldedDates property to this array. The program then sets the TodayDate property, and uses a new SelectionRange object to specify the dates that the control should initially display as selected.
' Get the first Monday in the allowed range. Dim mon As DateTime mon = CalReservation.MinDate Select Case mon.DayOfWeek Case DayOfWeek.Tuesday mon = mon.AddDays(6) Case DayOfWeek.Wednesday mon = mon.AddDays(5) Case DayOfWeek.Thursday mon = mon.AddDays(4) Case DayOfWeek.Friday mon = mon.AddDays(3) Case DayOfWeek.Saturday mon = mon.AddDays(2) Case DayOfWeek.Sunday mon = mon.AddDays(1) End Select ' Make an array of the allowed Mondays. Dim num_mondays As Integer Dim mondays() As DateTime = Nothing Do While mon <= CalReservation.MaxDate num_mondays += 1 ReDim Preserve mondays(num_mondays - 1) mondays(num_mondays - 1) = mon CalReservation.AddBoldedDate(mon) mon = mon.AddDays(7) Loop ' Bold the Mondays. CalReservation.BoldedDates = mondays ' Set today's date to 6/27/2005. CalReservation.TodayDate = New Date(2005, 6, 27) ' Start with the dates 7/28/2005 - 6/30/2005 selected. CalReservation.SelectionRange = _ New SelectionRange( _ New Date(2005, 6, 28), _ New Date(2005, 6, 30))
The following code shows how the program can display the dates selected by the control. It presents a message box showing the control’s SelectionStart and SelectionEnd properties. The result would be similar to 6/28/2005 to 6/30/2005.
Private Sub btnOK_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnOK.Click MessageBox.Show( _ calReservation.SelectionStart & " to " & _ calReservation.SelectionEnd) End Sub
The MonthCalendar control provides several useful methods. The following table describes the most useful.
Method | Purpose |
---|---|
AddAnnuallyBoldedDate | Adds a date to the control’s array of annually bolded dates. You must call UpdateBoldedDates after using this method. |
AddBoldedDate | Adds a date to the control’s array of bolded dates. You must call UpdateBoldedDates after using this method. |
AddMonthlyBoldedDate | Adds a date to the control’s array of monthly bolded dates. You must call UpdateBoldedDates after using this method. |
GetDisplayRange | Returns a SelectionRange object that indicates the range of dates currently displayed by the control. If this method’s visible parameter is True, the SelectionRange includes only dates that are included in the months that are visible (1/1/2005 to 6/30/2005 in Figure G-13). If this parameter is False, the SelectionRange includes all of the displayed dates even if they are in the months before or after the first and last months displayed (12/26/2004 to 7/9/2005 in Figure G-13). |
RemoveAllAnnuallyBoldedDates | Empties the control’s array of annually bolded dates. You must call UpdateBoldedDates after using this method. |
RemoveAllBoldedDates | Empties the control’s array of bolded dates. You must call UpdateBoldedDates after using this method. |
RemoveAllMonthlyBoldedDates | Empties the control’s array of monthly bolded dates. You must call UpdateBoldedDates after using this method. |
RemoveAnnuallyBoldedDate | Removes a specific annually bolded date. You must call UpdateBoldedDates after using this method. |
RemoveBoldedDate | Removes a specific bolded date. You must call Update Bolded?Dates after using this method. |
RemoveMonthlyBoldedDate | Removes a specific monthly bolded date. You must call UpdateBoldedDates after using this method. |
SetCalendarDimensions | Sets the control’s CalendarDimensions property. |
SetDate | Selects the specified date. |
SetSelectionRange | Selects the range defined by two dates. |
UpdateBoldedDates | Makes the control update itself to show changes to its bolded dates. |
The control’s bolded dates, monthly bolded dates, and annually bolded dates are all tracked separately and the control displays any date that is listed in any of those groups as bold. That means, for instance, that the RemoveAllBoldedDates subroutine does not change the monthly bolded dates or annually bolded dates.
The following code sets April 1 as an annually bolded date and January 13 as a monthly bolded date. It then removes all of the nonspecific bolded dates and calls UpdateBoldedDates. The result is that April 1 in every year is bold and that the 13th of every month is bold.
calStartDate.AddAnnuallyBoldedDate(#4/1/2005#) calStartDate.AddMonthlyBoldedDate(#1/13/2005#) calStartDate.RemoveAllBoldedDates() calStartDate.UpdateBoldedDates()