Month Calendar Control Macros
Month Calendar Control Reference

Month Calendar Control Macros


This section contains information about the macros used with month calendar controls.

MonthCal_GetColor

COLORREF MonthCal_GetColor(
    HWND hwndMC,
    INT iColor
);

Retrieves the color for a given portion of a month calendar control. You can use this macro or send the MCM_GETCOLOR message explicitly.

hwndMC
Handle to a month calendar control.
iColor
INT value specifying which month calendar color to retrieve. This value can be one of the following:
MCSC_BACKGROUND Retrieve the background color displayed between months.
MCSC_MONTHBK Retrieve the background color displayed within the month.
MCSC_TEXT Retrieve the color used to display text within a month.
MCSC_TITLEBK Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Version 4.70

MonthCal_GetCurSel

BOOL MonthCal_GetCurSel(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Retrieves the currently selected date. You can use this macro or send the MCM_GETCURSEL message explicitly.

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that will receive the currently selected date information. This parameter must be a valid address and cannot be NULL.

Version 4.70

MonthCal_GetFirstDayOfWeek

DWORD MonthCal_GetFirstDayOfWeek(
    HWND hwndMC
);

Retrieves the first day of the week for a month calendar control. You can use this macro or send the MCM_GETFIRSTDAYOFWEEK message explicitly.

hwndMC
Handle to a month calendar control.

Version 4.70

MonthCal_GetMaxSelCount

DWORD MonthCal_GetMaxSelCount(
    HWND hwndMC
);

Retrieves the maximum date range that can be selected in a month calendar control. You can use this macro or send the MCM_GETMAXSELCOUNT message explicitly.

hwndMC
Handle to a month calendar control.

You can change the maximum date range that can be selected by using the MCM_SETMAXSELCOUNT message.

Version 4.70

MonthCal_GetMaxTodayWidth

DWORD MonthCal_GetMaxTodayWidth(
    HWND hwndMC
);

Retrieves the maximum width of the "today" string in a month calendar control. This includes the label text and the date text. You can use this macro or send the MCM_GETMAXTODAYWIDTH message explicitly.

hwndMC
Handle to a month calendar control.

Version 4.70

MonthCal_GetMinReqRect

BOOL MonthCal_GetMinReqRect(
    HWND hwndMC,
    LPRECT lpRectInfo
);

Retrieves the minimum size required to display a full month in a month calendar control. Size information is presented in the form of a RECT structure. You can use this macro or send the MCM_GETMINREQRECT message explicitly.

hwndMC
Handle to a month calendar control.
lpRectInfo
Address of a RECT structure that will receive bounding rectangle information. This parameter must be a valid address and cannot be NULL.

The top and left members of lpRectInfo will always be zero. The right and bottom members represent the minimum cx and cy required for the control.

The minimum required window size for a month calendar control depends on the currently selected font.

Version 4.70

MonthCal_GetMonthDelta

INT MonthCal_GetMonthDelta(
    HWND hwndMC
);

Retrieves the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can use this macro or send the MCM_GETMONTHDELTA message explicitly.

hwndMC
Handle to a month calendar control.

Version 4.70

MonthCal_GetMonthRange

DWORD MonthCal_GetMonthRange(
    HWND hwndMC,
    DWORD dwFlag,
    LPSYSTEMTIME lprgSysTimeArray
);

Retrieves date information (using SYSTEMTIME structures) that represents the high and low limits of a month calendar control's display. You can use this macro or send the MCM_GETMONTHRANGE message explicitly.

hwndMC
Handle to a month calendar control.
dwFlag
Value specifying the scope of the range limits to be retrieved. This value must be one of the following:
GMR_DAYSTATE Include preceding and trailing months of visible range that are only partially displayed.
GMR_VISIBLE Include only those months that are entirely displayed.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the scope specified by dwFlag. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Version 4.70

MonthCal_GetRange

DWORD MonthCal_GetRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Retrieves the minimum and maximum allowable dates set for a month calendar control. You can use this macro or send the MCM_GETRANGE message explicitly.

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the date limit information. The minimum limit is set in lprgSysTimeArray[0], and lprgSysTimeArray[1] receives the maximum limit. If either element is set to all zeros, then no corresponding limit is set for the month calendar control. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Version 4.70

MonthCal_GetSelRange

BOOL MonthCal_GetSelRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Retrieves date information that represents the upper and lower limits of the date range currently selected by the user. You can use this macro or send the MCM_GETSELRANGE message explicitly.

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the user's selection. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Version 4.70

MonthCal_GetToday

BOOL MonthCal_GetToday(
    HWND hwndMC,
    LPSYSTEMTIME lpToday
);

Retrieves the date information for the date specified as "today" for a month calendar control. You can use this macro or send the MCM_GETTODAY message explicitly.

hwndMC
Handle to a month calendar control.
lpToday
Address of a SYSTEMTIME structure that will receive the date information. The time members of this structure will not be modified. This parameter must be a valid address and cannot be NULL.

Version 4.70

MonthCal_GetUnicodeFormat

BOOL MonthCal_GetUnicodeFormat(
    HWND hwnd
);

Retrieves the UNICODE character format flag for the control. You can use this macro or send the MCM_GETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.

See also MonthCal_SetUnicodeFormat

MonthCal_HitTest

DWORD MonthCal_HitTest(
    HWND hwndMC,
    PMCHITTESTINFO pMCHitTest
);

Determines which portion of a month calendar control is at a given point on the screen. You can use this macro or send the MCM_HITTEST message explicitly.

hwndMC
Handle to a month calendar control.
pMCHitTest
Address of an MCHITTESTINFO structure. Upon calling the macro, the cbSize member must be set to the size of the MCHITTESTINFO structure, and pt must be set to the point you want to hit test.

Version 4.70

MonthCal_SetColor

COLORREF MonthCal_SetColor(
    HWND hwndMC,
    INT iColor,
    COLORREF clr
);

Sets the color for a given portion of a month calendar control. You can use this macro or send the MCM_SETCOLOR message explicitly.

hwndMC
Handle to a month calendar control.
iColor
INT value specifying which month calendar color to set. This value can be one of the following:
MCSC_BACKGROUND Retrieve the background color displayed between months.
MCSC_MONTHBK Retrieve the background color displayed within the month.
MCSC_TEXT Retrieve the color used to display text within a month.
MCSC_TITLEBK Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.
clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Version 4.70

MonthCal_SetCurSel

BOOL MonthCal_SetCurSel(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Sets the currently selected date for a month calendar control. If the specified date is not in view, the control updates the display to bring it into view. You can use this macro or send the MCM_SETCURSEL message explicitly.

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the current selection. The time members of this structure are ignored.

Version 4.70

MonthCal_SetDayState

BOOL MonthCal_SetDayState(
    HWND hwndMC,
    INT iMonths,
    LPMONTHDAYSTATE lpDayStateArray
);

Sets the day states for all months that are currently visible within a month calendar control. You can use this macro or send the MCM_SETDAYSTATE message explicitly.

hwndMC
Handle to a month calendar control.
iMonths
INT value indicating how many elements are in the array that lpDayStateArray points to.
lpDayStateArray
Address of an array of MONTHDAYSTATE values that define how the month calendar control will draw each day in its display.

The array at lpDayStateArray must contain as many elements as the value returned by the following macro:

MonthCal_GetMonthRange(hwndMC, GMR_DAYSTATE, NULL);

The preceding macro returns the total number of months that are in complete or partial view within the month calendar's display.

Keep in mind that the array at lpDayStateArray must contain MONTHDAYSTATE values that correspond with all months currently in the control's display, in chronological order. This includes the two months only partially displayed before the first month and after the last month. For more information about preparing your array, see Preparing the MONTHDAYSTATE Array.

Version 4.70

MonthCal_SetFirstDayOfWeek

DWORD MonthCal_SetFirstDayOfWeek(
    HWND hwndMC,
    INT iDay
);

Sets the first day of the week for a month calendar control. You can use this macro or send the MCM_SETFIRSTDAYOFWEEK message explicitly.

hwndMC
Handle to a month calendar control.
iDay
INT value representing which day is to be set as the first day of the week. This value must be one of the day numbers.

If the first day of the week is set to anything other than the default (LOCALE_IFIRSTDAYOFWEEK), the control will not automatically update first-day-of-the-week changes based on locale changes.

Version 4.70

MonthCal_SetMaxSelCount

BOOL MonthCal_SetMaxSelCount(
    HWND hwndMC,
    UINT iMax
);

Sets the maximum number of days that can be selected in a month calendar control. You can use this macro or send the MCM_SETMAXSELCOUNT message explicitly.

hwndMC
Handle to a month calendar control.
iMax
INT value that will be set to represent the maximum number of days that can be selected.

Version 4.70

MonthCal_SetMonthDelta

INT MonthCal_SetMonthDelta(
    HWND hwndMC,
    INT iDelta
);

Sets the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can use this macro or send the MCM_SETMONTHDELTA message explicitly.

hwndMC
Handle to a month calendar control.
iDelta
Value representing the number of months to be set as the control's scroll rate. If this value is zero, the month delta is reset to the default, which is the number of months displayed in the control.

Version 4.70

MonthCal_SetRange

BOOL MonthCal_SetRange(
    HWND hwndMC,
    DWORD fWhichLimit,
    LPSYSTEMTIME lprgSysTimeArray
);

Sets the minimum and maximum allowable dates for a month calendar control. You can use this macro or send the MCM_SETRANGE message explicitly.

hwndMC
Handle to a month calendar control.
fWhichLimit
Flag values that specify which date limits are being set. This value must be one or both of the following:
GDTR_MAX The maximum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[1] must contain date information.
GDTR_MIN The minimum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[0] must contain date information.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain the date limits. The maximum limit must be in lpSysTimeArray[1] if GDTR_MAX is specified, and lpSysTimeArray[0] must contain the minimum limit if GDTR_MIN is specified.

Version 4.70

MonthCal_SetSelRange

BOOL MonthCal_SetSelRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Sets the selection for a month calendar control to a given date range. You can use this macro or send the MCM_SETSELRANGE message explicitly.

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain date information representing the selection limits. The first selected date must be specified in lpSysTimeArray[0], and the last selected date must be specified in lpSysTimeArray[1]. The time members of these structures are ignored.

Version 4.70

MonthCal_SetToday

void MonthCal_SetToday(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Sets the "today" selection for a month calendar control. You can use this macro or send the MCM_SETTODAY message explicitly.

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the "today" selection for the control. If this parameter is set to NULL, the control returns to the default setting. The time members of this structure are ignored.

If the "today" selection is set to any date other than the default, the following conditions apply:

Version 4.70

MonthCal_SetUnicodeFormat

BOOL MonthCal_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the MCM_SETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also MonthCal_GetUnicodeFormat

Month Calendar Control Notification Messages

This section contains information about the notification messages used with month calendar controls.

MCN_GETDAYSTATE

MCN_GETDAYSTATE
    lpNMDayState = (LPNMDAYSTATE) lParam;

Sent by a month calendar control to request information about how individual days should be displayed. This notification message is sent only by month calendar controls that use the MCS_DAYSTATE style, and it is sent in the form of a WM_NOTIFY message.

lpNMDayState
Address of an NMDAYSTATE structure. The structure contains information about the time frame for which the control needs information, and it receives the address of an array that provides this data.

Handling this notification message allows your application to customize its display by specifying that certain days be displayed in bold. For more information about processing this message, see Processing the MCN_GETDAYSTATE Notification Message.

Version 4.70

MCN_SELCHANGE

MCN_SELCHANGE
    lpNMSelChange = (LPNMSELCHANGE) lParam;

Sent by a month calendar control when the currently selected date or range of dates changes. This notification message is sent in the form of a WM_NOTIFY message.

For example, the control sends MCN_SELCHANGE when the user explicitly changes his or her selection within the current month or when the selection is implicitly changed in response to next/previous month navigation.

lpNMSelChange
Address of an NMSELCHANGE structure that contains information about the currently selected date range.

This notification message is similar to MCN_SELECT, but it is sent in response to any selection change. MCN_SELECT is sent only for an explicit date selection.

Version 4.70

MCN_SELECT

MCN_SELECT
    lpNMSelChange = (LPNMSELCHANGE) lParam;

Sent by a month calendar control when the user makes an explicit date selection within a month calendar control. This notification is sent in the form of a WM_NOTIFY message.

lpNMSelChange
Address of an NMSELCHANGE structure that contains information about the currently selected date range.

This notification message is similar to MCN_SELCHANGE, but it is sent only in response to a user's explicit date selections. MCN_SELCHANGE applies to any selection change.

Version 4.70

NM_RELEASEDCAPTURE (monthcal)

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam; 

Notifies a monthcal control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Version 4.71.

Month Calendar Control Structures

This section contains information about the structures used with month calendar controls.

MCHITTESTINFO

typedef struct {
    UINT       cbSize;
    POINT      pt;
    UINT       uHit;   // An output member
    SYSTEMTIME st;     // An output member
} MCHITTESTINFO, *PMCHITTESTINFO;

Carries information specific to hit-testing points for a month calendar control. This structure is used with the MCM_HITTEST message and the corresponding MonthCal_HitTest macro.

cbSize
Size of this structure, in bytes.
pt
POINT structure that contains information about the point to be hit-tested.
uHit
Output member that receives a bit flag representing the result of the hit-test operation. This value will be one of the following:
MCHT_CALENDARBK The given point was in the calendar's background.
MCHT_CALENDARDATE The given point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the given point.
MCHT_CALENDARDATENEXT The given point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV The given point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY The given point was over a day abbreviation ("Fri", for example). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM The given point was over a week number (MCS_WEEKNUMBERS style only). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NOWHERE The given point was not on the month calendar control, or it was in an inactive portion of the control.
MCHT_TITLEBK The given point was over the background of a month's title.
MCHT_TITLEBTNNEXT The given point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV The given point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH The given point was in a month's title bar, over a month name.
MCHT_TITLEYEAR The given point was in a month's title bar, over the year value.
st
SYSTEMTIME structure that receives date and time information specific to the location that was hit-tested.

Version 4.70

NMDAYSTATE

typedef struct tagNMDAYSTATE {
    NMHDR           nmhdr;
    SYSTEMTIME      stStart;
    int             cDayState;
    LPMONTHDAYSTATE prgDayState; 
} NMDAYSTATE, FAR * LPNMDAYSTATE;

Carries information required to process the MCN_GETDAYSTATE notification message. All members of this structure are for input, except prgDayState, which the receiving application must set when processing MCN_GETDAYSTATE.

nmhdr
NMHDR structure that contains information about this notification message.
stStart
SYSTEMTIME structure that contains the starting date.
cDayState
INT value specifying the total number of elements that must be in the array at prgDayState.
prgDayState
Address of an array of MONTHDAYSTATE values. This must be set to point to an array that contains as many elements as specified in cDayState. The first element in the array corresponds to the date in stStart.

Version 4.70

NMSELCHANGE

typedef struct tagNMSELCHANGE{
    NMHDR           nmhdr;
    SYSTEMTIME      stSelStart;
    SYSTEMTIME      stSelEnd;
} NMSELCHANGE, FAR * LPNMSELCHANGE;

Carries information required to process the MCN_SELCHANGE notification message.

nmhdr
NMHDR structure that contains information about this notification message.
stSelStart
SYSTEMTIME structure that contains the date for the first day in the user's selection range.
stSelEnd
SYSTEMTIME structure that contains the date for the last day in the user's selection range.

Version 4.70

Month Calendar Control Data Types

This section contains information about the data types used with month calendar controls.

MONTHDAYSTATE

This is a new data type that is defined in Commctrl.h as follows:

typedef DWORD MONTHDAYSTATE, FAR * LPMONTHDAYSTATE;

The MONTHDAYSTATE type is a bit field, where each bit (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.

This data type is used with the MCM_SETDAYSTATE message and the corresponding macro, MonthCal_SetDayState. When MONTHDAYSTATE values are used in reference to months shorter than 31 days, only the needed bits will be accessed.

Version 4.70.

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