Visual Basic Concepts

Using the MonthView Control

The MonthView control makes it easy for users to view and set date information via a calendar-like interface. Users can select a single date or a range of dates.

The control can be navigated using either the keyboard or mouse. Buttons at the top of the control are used to scroll months in and out of view.

In addition, the control has the ability to display up to 12 months at a time. This can be helpful when you want to give users the ability to view date information around the date of interest.

MonthView control

Possible Uses

• To present date information where a calendar representation of a date is easier to understand than that of a Label or Textbox control.

• To give users the ability to choose a date with the click of a mouse rather than typing a date value.

• To enable users to view multiple months as part of an advanced booking system such as those used by hotels and airlines.

Setting and Returning Dates

The currently selected date in the control is determined by the Value property. You can set the Value of the control before it is displayed (for example, in the form's Load event) to determine which date will be initially selected in the control:

MonthView1.Value = "10/31/97"

By default, the control's Value is set to the current date, and the current date is selected when the control first appears. If you change the MonthView's Value through code, the control will be updated immediately to reflect the new setting.

Certain events of the control can also be used to return date values. For example, the DateClick event is fired whenever the user clicks on a date in the control. The DateClick event returns a DateClicked value that evaluates to the date the user clicked. Similarly, the DateDblClick event returns a DateDblClicked value indicating the date that was double-clicked to cause the event. When using these events, you should refer to the value returned by the event, rather than the Value property of the control, as Value is not updated until after the event has occurred.

The Value property returns a date value that you can format in whatever manner you wish. The MonthView control also has several properties that return specific date information. The Month property returns the integer value (1-12) of the month containing the currently selected date. The Day property returns the day number (1-31) currently selected, and the DayOfWeek property returns a value indicating the day of the week the selected date falls on (values correspond to the values of vbDayOfWeek constants.) The Year property returns the year containing the selected date as an integer value. Finally, there is a Week property that will return the number of the week containing the selected date.

These properties can be set as well as read at run time, with varying effects on the currently selected date. For example, changing the value of the DayOfWeek property will select the date that falls on the specified day in the same week. This will change the value of the Day property, but depending on how the week falls, it may also change the value of the Month property. Changing the value of the Year property will cause the current date to be selected in the specified year, which may affect the value of DayOfWeek.

You should be especially careful when changing the value of the Week property. Setting a different week as the current week will not change the value of DayOfWeek, but will affect the value of Day, and possibly the values of Week, Month or even Year. For example, if the user has selected a Friday, and you set the value of Week to 52 in a year that ends on a Wednesday, the value of Week will become 1, and the values of Month and Year will also change. Weeks 1 and 52 will usually overlap.

Selecting A Range of Dates

You can use the MonthView control to display a contiguous range of dates, or to allow the user to select a date range. In order to extend the selection to more than one date, the MultiSelect property must be set to True. You can control the maximum number of days that may be selected by changing the value of the MaxSelCount property. By default, the maximum selection allowed is seven days.

The SelStart and SelEnd properties determine which days are selected. You can check the values of these properties to find out what range the user has selected. If only one date is selected, the two values will be the same. You can also set the values of these properties in code, which will cause a range of dates to become selected in the control. When setting the SelStart and SelEnd properties through code, you must observe the following rules:

• The SelStart date must occur before the SelEnd date.

• The selected range must contain the currently selected date. If necessary, you should set the Value property to one of the dates in the range before setting the SelStart and SelEnd values.

• The number of dates included in the range cannot exceed the maximum range size as specified by MaxSelCount.

For example, to select the week before Halloween through code, you would use the following:

MonthView1.Value = "10/31/97"
MonthView1.MaxSelCount = 7
MonthView1.SelStart = "10/25/97"
MonthView1.SelEnd = "10/31/97"

Formatting the Control's Appearance

The MonthView control allows you to customize its appearance in many ways. Various color attributes such as MonthBackColor, TitleBackColor, TitleForeColor and TrailingForeColor enable you to create a unique color scheme or the control. For example, TrailingForeColor determines the color of the dates that precede and follow the displayed month or months.

The font settings for the control determine the width and height of the control. Using larger fonts causes the control to grow to accommodate the increased font size. Conversely, you can set the font to a smaller size to shrink the control. Font size is set through the Font property.

Displaying More Than One Month

The MonthView control can display from one to twelve months at a time. You specify how many months will be displayed and how they will be arranged within the control. You do this by using the MonthRows and MonthColumns properties. For example, setting MonthRows to 2 and MonthColumns to 3 would result in a MonthView control that displayed six months at a time. Clicking on the arrow buttons at the top of the control would scroll the next six months or the previous six months into view.

Individual months are separated by a separator bar. The size of the separator is dependent on control size and display characteristics, but you can retrieve the dimensions used via the SeperatorHeight and SeparatorWidth properties. You can also retrieve the size of a single calendar by using the CalendarWidth and CalendarHeight properties. Together these properties are useful in determining how the control will change size if another row or column is added, and adjusting the size and position of your controls accordingly.

Other Formatting Settings

You can determine which day of the week will appear as the first day by changing the value of the StartOfWeek property. You can choose to display week numbers in the control by setting the ShowWeekNumbers property to True. Week numbers appear in a separate column to the left of the first day of the week. The display of the current date at the bottom of the control can be enabled or disabled using the ShowToday property.

Formatting Specific Days

Any day number on the MonthView control can also have its font set to bold. This capability can be used to draw attention to dates (i.e. holidays, vacations, etc.) or just distinguish them from ordinary dates. More than one date can be bolded at the same time. Although the bold information for a day is not preserved while scrolling from month to month, this behavior can be simulated using the GetDayBold event.

The following example makes all Sundays bold, even when new months are scrolled into view:

Private Sub MonthView1_GetDayBold(ByVal StartDate As Date, ByVal Count As Integer, State() As Boolean)
   Dim i As Integer
   i = vbSunday
   While i < Count
      State(i - MonthView1.StartOfWeek) = True
      i = i + 7
   Wend
End Sub

Keyboard Interface

The MonthView control can be manipulated using the keyboard. The following table describes the different actions you can perform with the control at runtime.

Navigating the MonthView

In addition to the two buttons at the top of the control, the MonthView control provides other ways to set the currently displayed month(s). You can display a particular month of any particular year.

To select a particular month

1. Click on the month name at the top of the calendar. A context menu will appear with the names of all the months.

2. From the menu, choose the name of the month you want to select.

The control will display the selected month in the current year.

To go directly to a particular year

1. Select the month you want.

2. Click on the year number at the top of the calendar. This will place it in edit mode.

3. Click the up/down scroll buttons to scroll the year.

4. Click anywhere outside the edit box or press the ENTER key when you are done.

The control will display the current month in the year you specified.

Distribution Note   The UpDown control is part of a group of ActiveX controls that are found in the MSCOMCT2.ocx file. To use the UpDown control in your application, you must add the MSCOMCT2.ocx file to the project. When distributing your application, install the MSCOMCT2.ocx file in the user’s Microsoft Windows System or System32 directory. For more information on how to add an ActiveX control to a project, see the Programmer’s Guide.