About Month Calendar Controls

About Month Calendar Controls


A month calendar control provides a simple and intuitive way for a user to select a date from a familiar interface. The following illustration shows a month calendar control in a dialog box.

Month calendar control in a dialog box.

An application creates a month calendar control by calling the CreateWindowEx function, specifying MONTHCAL_CLASS as the window class. The class is registered when the month calendar class is loaded from the common controls dynamic-link library (DLL). Register this class by calling the InitCommonControlsEx function, specifying the ICC_DATE_CLASSES bit flag in the accompanying INITCOMMONCONTROLSEX structure.

Note The month calendar control is implemented in version 4.70 and later of Comctl32.dll.

The Month Calendar Control User Interface

The month calendar control user interface allows the user to select a date from the displayed days or change the control's display in various ways.

Day States

Month calendar controls that use the MCS_DAYSTATE style support day states. The control uses day state information to determine how it draws specific days within the control. Day state information is expressed as a 32-bit data type, MONTHDAYSTATE. Each bit in a MONTHDAYSTATE bit field (1 through 31) represents the state of a day in a month. If a bit is on, the corresponding day will be displayed in bold; otherwise it will be displayed with no emphasis.

An application can explicitly set day state information by sending the MCM_SETDAYSTATE message or by using the corresponding macro, MonthCal_SetDayState. Additionally, month calendar controls that use the MCS_DAYSTATE style send MCN_GETDAYSTATE notification messages to request day state information. For more information on supporting day states, see Processing the MCN_GETDAYSTATE Notification Message and Preparing the MONTHDAYSTATE Array.

Month Calendar Control Styles

Month calendar controls have several styles that determine their appearance and behavior. When you create the control using CreateWindowEx, include the desired styles in the dwStyle parameter.

After creating the control, you can change all of the styles except for MCS_DAYSTATE and MCS_MULTISELECT. To change these styles, you will need to destroy the existing control and create a new one that has the desired styles. To retrieve or change any other window styles, use the GetWindowLong and SetWindowLong functions.

Month calendar controls that use the MCS_MULTISELECT style allow the user to select a range of days. By default, the control allows the user to select seven contiguous days. Your application can change the control's default behavior by using the MCM_SETMAXSELCOUNT message or the accompanying macro, MonthCal_SetMaxSelCount.

When a month calendar control uses the MCS_WEEKNUMBERS style, it displays week numbers at the left side of each month. If the MCS_NOTODAY style is applied, the control no longer circles the current day.

The MCS_DAYSTATE style is helpful when you want the control to highlight specific dates by displaying them in bold. For more information, see Day States.

Month Calendar Control Notification Messages

A month calendar control sends notification messages when it receives user input or must request day state information (MCS_DAYSTATE style only). The control's parent receives these notifications as WM_NOTIFY messages.

The following notification messages are used with month calendar controls.
Notification Description
MCN_GETDAYSTATE Requests information about which days should be displayed in bold. For more information, see Preparing the MONTHDAYSTATE Array.
MCN_SELCHANGE Notifies the parent that the selected date or range of dates has changed. The control sends this notification when the user explicitly changes the selection within the current month or when the selection is implicitly changed in response to next/previous month navigation.
MCN_SELECT Notifies the parent that the user has explicitly selected a date.

Times in the Month Calendar Control

Because the month calendar control cannot be used to select a time, the time related fields of the SYSTEMTIME structure need to be handled differently. When the control is created, it will insert the current time into its "today" date and time.

When a time is later set programmatically, the control will either copy the time fields as they are or validate them first and then, if invalid, store the current default times. Following is a list of the messages that set a date and a description of how the time fields are treated by the message.

MCM_SETCURSEL The control will copy the time fields as they are, without validation or modification.
MCM_SETRANGE The time fields of the structures passed in will be validated. If they are valid, the time fields will be copied without modification. If they are invalid, the control will copy the time fields from the "today" date and time.
MCM_SETSELRANGE The time fields of the structures passed in will be validated. If they are valid, the time fields will be copied without modification. If they are invalid, the control will retain the time fields from the current selection ranges.
MCM_SETTODAY The control will copy the time fields as they are, without validation or modification.

When a date is retrieved from the control, the time fields will be copied from the stored times without modification. Handling of the time fields by the control is provided as a convenience to the programmer. The control does not examine or modify the time fields as a result of any operation other than those listed above.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.