CMonthCalCtrl Class

Article
08/06/2021

Encapsulates the functionality of a month calendar control.

Syntax

class CMonthCalCtrl : public CWnd

Members

Public Constructors

Name	Description
CMonthCalCtrl::CMonthCalCtrl	Constructs a `CMonthCalCtrl` object.

Public Methods

Name	Description
CMonthCalCtrl::Create	Creates a month calendar control and attaches it to the `CMonthCalCtrl` object.
CMonthCalCtrl::GetCalendarBorder	Retrieves the width of the border of the current month calendar control.
CMonthCalCtrl::GetCalendarCount	Retrieves the number of calendars displayed in the current month calendar control.
CMonthCalCtrl::GetCalendarGridInfo	Retrieves information about the current month calendar control.
CMonthCalCtrl::GetCalID	Retrieves the calendar identifier for the current month calendar control.
CMonthCalCtrl::GetColor	Gets the color of a specified area of a month calendar control.
CMonthCalCtrl::GetCurrentView	Retrieves the view that is currently displayed by the current month calendar control.
CMonthCalCtrl::GetCurSel	Retrieves the system time as indicated by the currently-selected date.
CMonthCalCtrl::GetFirstDayOfWeek	Gets the first day of the week to be displayed in the leftmost column of the calendar.
CMonthCalCtrl::GetMaxSelCount	Retrieves the current maximum number of days that can be selected in a month calendar control.
CMonthCalCtrl::GetMaxTodayWidth	Retrieves the maximum width of the "Today" string for the current month calendar control.
CMonthCalCtrl::GetMinReqRect	Retrieves the minimum size required to show a full month in a month calendar control.
CMonthCalCtrl::GetMonthDelta	Retrieves the scroll rate for a month calendar control.
CMonthCalCtrl::GetMonthRange	Retrieves date information representing the high and low limits of a month calendar control's display.
CMonthCalCtrl::GetRange	Retrieves the current minimum and maximum dates set in a month calendar control.
CMonthCalCtrl::GetSelRange	Retrieves date information representing the upper and lower limits of the date range currently selected by the user.
CMonthCalCtrl::GetToday	Retrieves the date information for the date specified as "today" for a month calendar control.
CMonthCalCtrl::HitTest	Determines which section of a month calendar control is at a given point on the screen.
CMonthCalCtrl::IsCenturyView	Indicates whether the current view of the current month calendar control is the century view.
CMonthCalCtrl::IsDecadeView	Indicates whether the current view of the current month calendar control is the decade view.
CMonthCalCtrl::IsMonthView	Indicates whether the current view of the current month calendar control is the month view.
CMonthCalCtrl::IsYearView	Indicates whether the current view of the current month calendar control is the year view.
CMonthCalCtrl::SetCalendarBorder	Sets the width of the border of the current month calendar control.
CMonthCalCtrl::SetCalendarBorderDefault	Sets the default width of the border of the current month calendar control.
CMonthCalCtrl::SetCalID	Sets the calendar identifier for the current month calendar control.
CMonthCalCtrl::SetCenturyView	Sets the current month calendar control to display the century view.
CMonthCalCtrl::SetColor	Sets the color of a specified area of a month calendar control.
CMonthCalCtrl::SetCurrentView	Sets the current month calendar control to display the specified view.
CMonthCalCtrl::SetCurSel	Sets the currently selected date for a month calendar control.
CMonthCalCtrl::SetDayState	Sets the display for days in a month calendar control.
CMonthCalCtrl::SetDecadeView	Sets the current month calendar control to the decade view.
CMonthCalCtrl::SetFirstDayOfWeek	Sets the day of week to be displayed in the leftmost column of the calendar.
CMonthCalCtrl::SetMaxSelCount	Sets the maximum number of days that can be selected in a month calendar control.
CMonthCalCtrl::SetMonthDelta	Sets the scroll rate for a month calendar control.
CMonthCalCtrl::SetMonthView	Sets the current month calendar control to display the month view.
CMonthCalCtrl::SetRange	Sets the minimum and maximum allowed dates for a month calendar control.
CMonthCalCtrl::SetSelRange	Sets the selection for a month calendar control to a given date range.
CMonthCalCtrl::SetToday	Sets the calendar control for the current day.
CMonthCalCtrl::SetYearView	Sets the current month calendar control to year view.
CMonthCalCtrl::SizeMinReq	Repaints the month calendar control to its minimum, one-month size.
CMonthCalCtrl::SizeRectToMin	For the current month calendar control, calculates the smallest rectangle that can contain all the calendars that fit in a specified rectangle.

Remarks

The month calendar control provides the user with a simple calendar interface, from which the user can select a date. The user can change the display by:

Scrolling backward and forward, from month to month.
Clicking the Today text to display the current day (if the MCS_NOTODAY style is not used).
Picking a month or a year from a pop-up menu.

You can customize the month calendar control by applying a variety of styles to the object when you create it. These styles are described in Month Calendar Control Styles in the Windows SDK.

The month calendar control can display more than one month, and it can indicate special days (such as holidays) by bolding the date.

For more information on using the month calendar control, see Using CMonthCalCtrl.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CMonthCalCtrl

Requirements

Header: afxdtctl.h

CMonthCalCtrl::CMonthCalCtrl

Constructs a CMonthCalCtrl object.

CMonthCalCtrl();

Remarks

You must call Create after you construct the object.

CMonthCalCtrl::Create

Creates a month calendar control and attaches it to the CMonthCalCtrl object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

virtual BOOL Create(
    DWORD dwStyle,
    const POINT& pt,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwStyle
Specifies the combination of Windows styles applied to the month calendar control. See Month Calendar Control Styles in the Windows SDK for more information about the styles.

rect
A reference to a RECT structure. Contains the position and size of the month calendar control.

pt
A reference to a POINT structure that identifies the location of the month calendar control.

pParentWnd
A pointer to a CWnd object that is the parent window of the month calendar control. It must not be NULL.

nID
Specifies the month calendar control's control ID.

Return Value

Nonzero if initialization was successful; otherwise 0.

Remarks

Create a month calendar control in two steps:

Call CMonthCalCtrl to construct a CMonthCalCtrl object.
Call this member function, which creates a month calendar control and attaches it to the CMonthCalCtrl object.

When you call Create, the common controls are initialized. The version of Create you call determines how it is sized:

To have MFC automatically size the control to one month, call the override that uses the pt parameter.
To size the control yourself, call the override of this function that uses the rect parameter.

Example

// Given two member objects m_calCtrl1 and m_calCtrl2, we can
// create them in one of two ways.

// Providing a point has the control with its top-left corner
// at that point and sized automatically to show one month
// page.

CPoint pt(10, 10);
VERIFY(m_calCtrl1.Create(WS_TABSTOP | WS_CHILD | WS_VISIBLE |
                             WS_BORDER | MCS_DAYSTATE,
                         pt, this, IDC_MONTHCALCTRL1));

// Providing a rectangle lets us completely control the size.
// The control will paint as many complete month pages in the
// control's area as possible.

CRect rect(300, 100, 470, 200);
VERIFY(m_calCtrl2.Create(WS_TABSTOP | WS_CHILD | WS_VISIBLE |
                             WS_BORDER | MCS_MULTISELECT,
                         rect, this, IDC_MONTHCALCTRL2));

CMonthCalCtrl::GetCalendarBorder

Retrieves the width of the border of the current month calendar control.

int GetCalendarBorder() const;

Return Value

The width of the control border, in pixels.

Remarks

This method sends the MCM_GETCALENDARBORDER message, which is described in the Windows SDK.

CMonthCalCtrl::GetCalendarCount

Retrieves the number of calendars displayed in the current month calendar control.

int GetCalendarCount() const;

Return Value

The number of calendars currently displayed in the month calendar control. The maximum allowed number of calendars is 12.

Remarks

This method sends the MCM_GETCALENDARCOUNT message, which is described in the Windows SDK.

CMonthCalCtrl::GetCalendarGridInfo

Retrieves information about the current month calendar control.

BOOL GetCalendarGridInfo(PMCGRIDINFO pmcGridInfo) const;

Parameters

pmcGridInfo
[out] Pointer to a MCGRIDINFO structure that receives information about the current month calendar control. The caller is responsible for allocating and initializing this structure.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the MCM_GETCALENDARGRIDINFO message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example uses the GetCalendarGridInfo method to retrieve the calendar date that the current month calendar control displays.

WCHAR name[26];
name[0] = _T('\0');
MCGRIDINFO gridInfo;
gridInfo.cbSize = sizeof(MCGRIDINFO);
gridInfo.dwPart = MCGIP_CALENDARHEADER;
gridInfo.dwFlags = MCGIF_NAME;
gridInfo.iCalendar = 0;
gridInfo.pszName = reinterpret_cast<PWSTR>(&name);
gridInfo.cchName = sizeof(name);

m_monthCalCtrl.GetCalendarGridInfo(&gridInfo);

CString str;
CString calendarDate(name);
str.Format(_T("Calendar date: '%s'"), calendarDate);
AfxMessageBox(str, MB_ICONINFORMATION);

CMonthCalCtrl::GetCalID

Retrieves the calendar identifier for the current month calendar control.

CALID GetCalID() const;

Return Value

One of the calendar identifier constants.

Remarks

A calendar identifier denotes a region-specific calendar, such as the Gregorian (localized), Japanese, or Hijri calendars. Your application can use a calendar identifier that has various language support functions.

This method sends the MCM_GETCALID message, which is described in the Windows SDK.

CMonthCalCtrl::GetColor

Retrieves the color of an area of the month calendar control specified by nRegion.

COLORREF GetColor(int nRegion) const;

Parameters

nRegion
The region of the month calendar control from which the color is retrieved. For a list of values, see the nRegion parameter of SetColor.

Return Value

A COLORREF value specifying the color associated with the portion of the month calendar control, if successful. Otherwise, this member function returns -1.

CMonthCalCtrl::GetCurrentView

Retrieves the view that is currently displayed by the current month calendar control.

DWORD GetCurrentView() const;

Return Value

The current view, which is indicated by one of the following values:

Value	Meaning
MCMV_MONTH	Monthly view
MCMV_YEAR	Annual view
MCMV_DECADE	Decade view
MCMV_CENTURY	Century view

Remarks

This method sends the MCM_GETCURRENTVIEW message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example reports which view the month calendar control currently displays.

CString str;
CString msg = _T("The current calendar displays %s view.");
DWORD view = m_monthCalCtrl.GetCurrentView();
switch (view)
{
case MCMV_MONTH:
   str.Format(msg, _T("month"));
   break;
case MCMV_YEAR:
   str.Format(msg, _T("year"));
   break;
case MCMV_DECADE:
   str.Format(msg, _T("decade"));
   break;
case MCMV_CENTURY:
   str.Format(msg, _T("century"));
   break;
default:
   str.Format(msg, _T("an unknown"));
   break;
}
AfxMessageBox(str, MB_ICONINFORMATION);

CMonthCalCtrl::GetCurSel

Retrieves the system time as indicated by the currently-selected date.

BOOL GetCurSel(COleDateTime& refDateTime) const;  BOOL GetCurSel(CTime& refDateTime) const;

BOOL GetCurSel(LPSYSTEMTIME pDateTime) const;

Parameters

refDateTime
A reference to a COleDateTime object or a CTime object. Receives the current time.

pDateTime
A pointer to a SYSTEMTIME structure that will receive the currently-selected date information. This parameter must be a valid address and cannot be NULL.

Return Value

Nonzero if successful; otherwize 0.

Remarks

This member function implements the behavior of the Win32 message MCM_GETCURSEL, as described in the Windows SDK.

Note

This member function fails if the style MCS_MULTISELECT is set.

In MFC's implementation of GetCurSel, you can specify a COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

CMonthCalCtrl::GetFirstDayOfWeek

Gets the first day of the week to be displayed in the leftmost column of the calendar.

int GetFirstDayOfWeek(BOOL* pbLocal = NULL) const;

Parameters

pbLocal
A pointer to a BOOL value. If the value is non-zero, the control's setting does not match the setting in the control panel.

Return Value

An integer value that represents the first day of the week. See Remarks for more information on what these integers represent.

Remarks

This member function implements the behavior of the Win32 message MCM_GETFIRSTDAYOFWEEK, as described in the Windows SDK. The days of the week are represented as integers, as follows.

Value	Day of the week
0	Monday
1	Tuesday
2	Wednesday
3	Thursday
4	Friday
5	Saturday
6	Sunday

Example

See the example for CMonthCalCtrl::SetFirstDayOfWeek.

CMonthCalCtrl::GetMaxSelCount

Retrieves the current maximum number of days that can be selected in a month calendar control.

int GetMaxSelCount() const;

Return Value

An integer value that represents the total number of days that can be selected for the control.

Remarks

This member function implements the behavior of the Win32 message MCM_GETMAXSELCOUNT, as described in the Windows SDK. Use this member function for controls with the MCS_MULTISELECT style set.

Example

See the example for CMonthCalCtrl::SetMaxSelCount.

CMonthCalCtrl::GetMaxTodayWidth

Retrieves the maximum width of the "Today" string for the current month calendar control.

DWORD GetMaxTodayWidth() const;

Return Value

The width of the "Today" string, in pixels.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example demonstrates the GetMaxTodayWidth method.

DWORD width = m_monthCalCtrl.GetMaxTodayWidth();
CString str;
str.Format(_T("The maximum today width is %d."), width);
AfxMessageBox(str, MB_ICONINFORMATION);

Remarks

The user can return to the current date by clicking the "Today" string, which is displayed at the bottom of the month calendar control. The "Today" string includes label text and date text.

This method sends the MCM_GETMAXTODAYWIDTH message, which is described in the Windows SDK.

CMonthCalCtrl::GetMinReqRect

Retrieves the minimum size required to show a full month in a month calendar control.

BOOL GetMinReqRect(RECT* pRect) const;

Parameters

pRect
A pointer to a RECT structure that will receive bounding rectangle information. This parameter must be a valid address and cannot be NULL.

Return Value

If successful, this member function returns nonzero and lpRect receives the applicable bounding information. If unsuccessful, the member function returns 0.

Remarks

This member function implements the behavior of the Win32 message MCM_GETMINREQRECT, as described in the Windows SDK.

CMonthCalCtrl::GetMonthDelta

Retrieves the scroll rate for a month calendar control.

int GetMonthDelta() const;

Return Value

The scroll rate for the month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button once.

Remarks

This member function implements the behavior of the Win32 message MCM_GETMONTHDELTA, as described in the Windows SDK.

CMonthCalCtrl::GetMonthRange

Retrieves date information representing the high and low limits of a month calendar control's display.

int GetMonthRange(
    COleDateTime& refMinRange,
    COleDateTime& refMaxRange,
    DWORD dwFlags) const;

int GetMonthRange(
    CTime& refMinRange,
    CTime& refMaxRange,
    DWORD dwFlags) const;

int GetMonthRange(
    LPSYSTEMTIME pMinRange,
    LPSYSTEMTIME pMaxRange,
    DWORD dwFlags) const;

Parameters

refMinRange
A reference to a COleDateTime or CTime object containing the minimum date allowed.

refMaxRange
A reference to a COleDateTime or CTime object containing the maximum date allowed.

pMinRange
A pointer to a SYSTEMTIME structure containing the date at the lowest end of the range.

pMaxRange
A pointer to a SYSTEMTIME structure containing the date at the highest end of the range.

dwFlags
Value specifying the scope of the range limits to be retrieved. This value must be one of the following.

Value	Meaning
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.

Return Value

An integer that represents the range, in months, spanned by the two limits indicated by refMinRange and refMaxRange in the first and second versions, or pMinRange and pMaxRange in the third version.

Remarks

This member function implements the behavior of the Win32 message MCM_GETMONTHRANGE, as described in the Windows SDK. In MFC's implementation of GetMonthRange, you can specify COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

Example

See the example for CMonthCalCtrl::SetDayState.

CMonthCalCtrl::GetRange

Retrieves the current minimum and maximum dates set in a month calendar control.

DWORD GetRange(
    COleDateTime* pMinRange,
    COleDateTime* pMaxRange) const;

DWORD GetRange(
    CTime* pMinRange,
    CTime* pMaxRange) const;

DWORD GetRange(
    LPSYSTEMTIME pMinRange,
    LPSYSTEMTIME pMaxRange) const;

Parameters

pMinRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the lowest end of the range.

pMaxRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the highest end of the range.

Return Value

A DWORD that can be zero (no limits are set) or a combination of the following values that specify limit information.

Value	Meaning
GDTR_MAX	A maximum limit is set for the control; pMaxRange is valid and contains the applicable date information.
GDTR_MIN	A minimum limit is set for the control; pMinRange is valid and contains the applicable date information.

Remarks

This member function implements the behavior of the Win32 message MCM_GETRANGE, as described in the Windows SDK. In MFC's implementation of GetRange, you can specify a COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

Example

// This code fragment sets a variety of ranges in the
// control, and calls a separate function to show the
// set range to the user.

void CMonthCalDlg::OnBnClickedRangebutton()
{
   // set minimum of January 1st, 1995 with no maximum
   COleDateTime dtMin;
   COleDateTime dtMax;

   dtMin = COleDateTime(1995, 1, 1, 0, 0, 0);
   dtMax.SetStatus(COleDateTime::null);
   m_calCtrl1.SetRange(&dtMin, &dtMax);
   ShowRange(&m_calCtrl1);

   // set no minimum and a maximum of September 30th, 1997
   dtMin.SetStatus(COleDateTime::null);
   dtMax = COleDateTime(1997, 9, 30, 0, 0, 0);
   m_calCtrl1.SetRange(&dtMin, &dtMax);
   ShowRange(&m_calCtrl1);

   // set minimum of April 15, 1992 and maximum of June 5, 2002
   dtMin = COleDateTime(1992, 4, 15, 0, 0, 0);
   dtMax = COleDateTime(2002, 6, 5, 0, 0, 0);
   m_calCtrl1.SetRange(&dtMin, &dtMax);
   ShowRange(&m_calCtrl1);
}

void CMonthCalDlg::ShowRange(CMonthCalCtrl *pMoCalCtrl)
{
   ASSERT(pMoCalCtrl != NULL);
   CString strMessage;
   COleDateTime dtMinimum;
   COleDateTime dtMaximum;

   // Get the range
   DWORD dwResult = pMoCalCtrl->GetRange(&dtMinimum, &dtMaximum);

   // If a minimum was specified, format it
   // otherwise, indicate that there is no lower bound
   if (dwResult & GDTR_MIN)
      strMessage += dtMinimum.Format(_T("Minimum range is %x %X.\r\n"));
   else
      strMessage += _T("No minimum range.\r\n");

   // Treat maximum similarly
   if (dwResult & GDTR_MAX)
      strMessage += dtMaximum.Format(_T("Maximum range is %x %X.\r\n"));
   else
      strMessage += _T("No maximum range.\r\n");

   // Show the user
   AfxMessageBox(strMessage);
}

CMonthCalCtrl::GetSelRange

Retrieves date information representing the upper and lower limits of the date range currently selected by the user.

BOOL GetSelRange(
    COleDateTime& refMinRange,
    COleDateTime& refMaxRange) const;

BOOL GetSelRange(
    CTime& refMinRange,
    CTime& refMaxRange) const;

BOOL GetSelRange(
    LPSYSTEMTIME pMinRange,
    LPSYSTEMTIME pMaxRange) const;

Parameters

refMinRange
A reference to a COleDateTime or CTime object containing the minimum date allowed.

refMaxRange
A reference to a COleDateTime or CTime object containing the maximum date allowed.

pMinRange
A pointer to a SYSTEMTIME structure containing the date at the lowest end of the range.

pMaxRange
A pointer to a SYSTEMTIME structure containing the date at the highest end of the range.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_GETSELRANGE, as described in the Windows SDK. GetSelRange will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

In MFC's implementation of GetSelRange, you can specify COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

CMonthCalCtrl::GetToday

Retrieves the date information for the date specified as "today" for a month calendar control.

BOOL GetToday(COleDateTime& refDateTime) const;  BOOL GetToday(COleDateTime& refDateTime) const;

BOOL GetToday(LPSYSTEMTIME pDateTime) const;

Parameters

refDateTime
A reference to a COleDateTime or CTime object indicating the current day.

pDateTime
A pointer to a SYSTEMTIME structure that will receive the date information. This parameter must be a valid address and cannot be NULL.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_GETTODAY, as described in the Windows SDK. In MFC's implementation of GetToday, you can specify a COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

Example

void CMonthCalDlg::OnBnClickedGettodaybutton()
{
   COleDateTime timeToday;
   if (m_calCtrl1.GetToday(timeToday))
   {
      // Format the date information from the value we received
      // and post a message box about it.
      CString str = timeToday.Format(VAR_DATEVALUEONLY);
      AfxMessageBox(str);

      // Set the control's "today" indicator to be five
      // days previous.
      timeToday -= 5;
      m_calCtrl1.SetToday(timeToday);
   }
   else
   {
      // Something is wrong!
      ASSERT(FALSE);
   }
}

CMonthCalCtrl::HitTest

Determines which month calendar control, if any, is at a specified position.

DWORD HitTest(PMCHITTESTINFO pMCHitTest);

Parameters

void SetCalendarBorder(int cxyBorder);

Parameters

cxyBorder
[in] The width of the border, in pixels.

Remarks

If this method succeeds, the border width is set to the cxyBorder parameter. Otherwise, the border width is reset to the default value that is specified by the current theme, or zero if themes are not used.

This method sends the MCM_SETCALENDARBORDER message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example sets the border width of the month calendar control to eight pixels. Use the CMonthCalCtrl::GetCalendarBorder method to determine whether this method succeeded.

// Use the GetCalendarBorder() method to determine whether
// this method succeeded or failed.
m_monthCalCtrl.SetCalendarBorder(8);

CMonthCalCtrl::SetCalendarBorderDefault

Sets the default width of the border of the current month calendar control.

void SetCalendarBorderDefault();

Remarks

The border width is set to the default value specified by the current theme, or zero if themes are not used.

This method sends the MCM_SETCALENDARBORDER message, which is described in the Windows SDK.

CMonthCalCtrl::SetCalID

Sets the calendar identifier for the current month calendar control.

BOOL SetCalID(CALID calid);

Parameters

calid
[in] One of the calendar identifier constants.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

A calendar identifier specifies a region-specific calendar, such as the Gregorian (localized), Japanese, or Hijri calendars. Use the SetCalID method to display a calendar that is specified by the calid parameter if the locale that contains the calendar is installed on your computer.

This method sends the MCM_SETCALID message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example sets the month calendar control to display the Japanese Emperor Era calendar. The SetCalID method succeeds only if that calendar is installed on your computer.

BOOL rc = m_monthCalCtrl.SetCalID(CAL_JAPAN);
CString str = _T("Calendar change ");
;
if (rc == TRUE)
   str += _T("succeeded.");
else
{
   str += _T("failed.\n");
   str += _T("Perhaps this locale is not installed.");
}
AfxMessageBox(str, MB_ICONINFORMATION);

CMonthCalCtrl::SetCenturyView

Sets the current month calendar control to display the century view.

BOOL SetCenturyView();

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method uses the CMonthCalCtrl::SetCurrentView method to set the view to MCMV_CENTURY, which represents the century view.

CMonthCalCtrl::SetColor

Sets the color of a specified area of a month calendar control.

COLORREF SetColor(
    int nRegion,
    COLORREF ref);

Parameters

nRegion
An integer value specifying which month calendar color to set. This value can be one of the following.

Value	Meaning
MCSC_BACKGROUND	The background color displayed between months.
MCSC_MONTHBK	The background color displayed within the month.
MCSC_TEXT	The color used to display text within a month.
MCSC_TITLEBK	The background color displayed in the calendar's title.
MCSC_TITLETEXT	The color used to display text within the calendar's title.
MCSC_TRAILINGTEXT	The color used to display header and trailing-day text. Header and trailing days are the days from the previous and following months that appear on the current calendar.

ref
A COLORREF value for the new color setting for the specified portion of the month calendar control.

Return Value

A COLORREF value that represents the previous color setting for the specified portion of the month calendar control, if successful. Otherwise this message returns -1.

Remarks

This member function implements the behavior of the Win32 message MCM_SETCOLOR, as described in the Windows SDK.

Example

// Set colors for title text and title background to match
// the Control Panel settings for inactive window captions.
m_calCtrl1.SetColor(MCSC_TITLETEXT, ::GetSysColor(COLOR_INACTIVECAPTIONTEXT));
m_calCtrl1.SetColor(MCSC_TITLEBK, ::GetSysColor(COLOR_INACTIVECAPTION));

CMonthCalCtrl::SetCurrentView

Sets the current month calendar control to display the specified view.

BOOL SetCurrentView(DWORD dwNewView);

Parameters

dwNewView
[in] One of the following values that specifies a monthly, annual, decade, or century view.

MCMV_MONTH: Monthly view
MCMV_YEAR: Annual view
MCMV_DECADE: Decade view
MCMV_CENTURY: Century view

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the MCM_SETCURRENTVIEW message, which is described in the Windows SDK.

CMonthCalCtrl::SetCurSel

Sets the currently selected date for a month calendar control.

BOOL SetCurSel(const COleDateTime& refDateTime);
BOOL SetCurSel(const CTime& refDateTime);
BOOL SetCurSel(const LPSYSTEMTIME pDateTime);

Parameters

refDateTime
A reference to a COleDateTime or CTime object indicating the currently-selected month calendar control.

pDateTime
Pointer to a SYSTEMTIME structure that contains the date to be set as the current selection.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETCURSEL, as described in the Windows SDK. In MFC's implementation of SetCurSel, you can specify a COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

Example

void CMonthCalDlg::OnBnClickedCurselbutton()
{
   // All of these calls set the current selection to March 15, 1998.

   // with a COleDateTime
   COleDateTime dt1(1998, 3, 15, 0, 0, 0);
   m_calCtrl1.SetCurSel(dt1);

   // with a CTime
   CTime dt2(1998, 3, 15, 0, 0, 0);
   m_calCtrl1.SetCurSel(dt2);

   // with a SYSTEMTIME structure

   SYSTEMTIME sysTime;

   // set everything to zero
   memset(&sysTime, 0, sizeof(sysTime));

   // except for the date we want
   sysTime.wYear = 1998;
   sysTime.wMonth = 3;
   sysTime.wDay = 15;

   m_calCtrl1.SetCurSel(&sysTime);
}

CMonthCalCtrl::SetDayState

Sets the display for days in a month calendar control.

BOOL SetDayState(
    int nMonths,
    LPMONTHDAYSTATE pStates);

Parameters

nMonths
Value indicating how many elements are in the array that pStates points to.

pStates
A pointer to a MONTHDAYSTATE array of values that define how the month calendar control will draw each day in its display. The MONTHDAYSTATE data 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.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETDAYSTATE, as described in the Windows SDK.

Example

void CMonthCalDlg::OnBnClickedDaystatebutton()
{
   // First, we must find the visible range. The array we pass to the
   // SetDayState() function must be large enough to hold days for all
   // of the visible months. Even if a month is _partially_ visible,
   // we must have MONTHDAYSTATE data for it in the array we pass.
   // GetMonthRange() returns the range of days currently visible in
   // the control, along with a count of visible months. This array
   // will be up to 2 months larger than the number of "pages" visible
   // in the control.

   SYSTEMTIME timeFrom;
   SYSTEMTIME timeUntil;
   int nCount = m_calCtrl1.GetMonthRange(&timeFrom, &timeUntil, GMR_DAYSTATE);

   // Allocate the state array based on the return value.

   LPMONTHDAYSTATE pDayState;
   pDayState = new MONTHDAYSTATE[nCount];
   memset(pDayState, 0, sizeof(MONTHDAYSTATE) * nCount);

   // Find the first fully visible month.

   int nIndex = (timeFrom.wDay == 1) ? 0 : 1;

   // Set the 4th day, 19th day, and 26th day of the first
   // _fully_ visible month as bold.

   pDayState[nIndex] |= 1 << 3;  // 4th day
   pDayState[nIndex] |= 1 << 18; // 19th day
   pDayState[nIndex] |= 1 << 25; // 25th day

   // Set state and clean up

   VERIFY(m_calCtrl1.SetDayState(nCount, pDayState));
   delete[] pDayState;
}

CMonthCalCtrl::SetDecadeView

Sets the current month calendar control to the decade view.

BOOL SetDecadeView();

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method uses the CMonthCalCtrl::SetCurrentView method to set the view to MCMV_DECADE, which represents the decade view.

CMonthCalCtrl::SetFirstDayOfWeek

Sets the day of week to be displayed in the leftmost column of the calendar.

BOOL SetFirstDayOfWeek(
    int iDay,
    int* lpnOld = NULL);

Parameters

iDay
An integer value representing which day is to be set as the first day of the week. This value must be one of the day numbers. See GetFirstDayOfWeek for a description of the day numbers.

lpnOld
A pointer to an integer indicating the first day of the week previously set.

Return Value

Nonzero if the previous first day of the week is set to a value other than that of LOCALE_IFIRSTDAYOFWEEK, which is the day indicated in the control panel setting. Otherwise, this function returns 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETFIRSTDAYOFWEEK, as described in the Windows SDK.

Example

// This work isn't normally necessary, since the control will set
// the day of the week to match the system locale by itself.

// Ask the system for the first day of the week
TCHAR sz[2];
GetLocaleInfo(LOCALE_SYSTEM_DEFAULT, LOCALE_IFIRSTDAYOFWEEK, sz, 2);

// Convert from string result
int nFirstDay = _ttoi(sz);

// Set it and assert that it was successful.
m_calCtrl1.SetFirstDayOfWeek(nFirstDay);
ASSERT(m_calCtrl1.GetFirstDayOfWeek() == nFirstDay);

CMonthCalCtrl::SetMaxSelCount

Sets the maximum number of days that can be selected in a month calendar control.

BOOL SetMaxSelCount(int nMax);

Parameters

nMax
The value that will be set to represent the maximum number of selectable days.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETMAXSELCOUNT, as described in the Windows SDK.

Example

// The control needs to have the MCS_MULTISELECT style
// for the following code to work.

// change the maximum selection count
m_calCtrl2.SetMaxSelCount(10);

// check that the change was really made
ASSERT(m_calCtrl2.GetMaxSelCount() == 10);

CMonthCalCtrl::SetMonthDelta

Sets the scroll rate for a month calendar control.

int SetMonthDelta(int iDelta);

Parameters

iDelta
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.

Return Value

The previous scroll rate. If the scroll rate has not been previously set, the return value is 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETMONTHDELTA, as described in the Windows SDK.

CMonthCalCtrl::SetMonthView

Sets the current month calendar control to display the month view.

BOOL SetMonthView();

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method uses the CMonthCalCtrl::SetCurrentView method to set the view to MCMV_MONTH, which represents the month view.

Example

The first code example defines the variable, m_monthCalCtrl, that is used to programmatically access the month calendar control. This variable is used in the next example.

// Variable used to reference the month calendar control.
CMonthCalCtrl m_monthCalCtrl;
// Variable used to reference the splitbutton control.
CSplitButton m_splitButton;

The next code example sets the month calendar control to display the month, year, decade, and century views.

void CCMonthCalCtrl_s1Dlg::OnSetviewSetmonthview()
{
   m_monthCalCtrl.SetMonthView();
}

void CCMonthCalCtrl_s1Dlg::OnSetviewSetyearview()
{
   m_monthCalCtrl.SetYearView();
}

void CCMonthCalCtrl_s1Dlg::OnSetviewSetdecadeview()
{
   m_monthCalCtrl.SetDecadeView();
}

void CCMonthCalCtrl_s1Dlg::OnSetviewSetcenturyview()
{
   m_monthCalCtrl.SetCenturyView();
}

CMonthCalCtrl::SetRange

Sets the minimum and maximum allowable dates for a month calendar control.

BOOL SetRange(
    const COleDateTime* pMinRange,
    const COleDateTime* pMaxRange);

BOOL SetRange(
    const CTime* pMinRange,
    const CTime* pMaxRange);

BOOL SetRange(
    const LPSYSTEMTIME pMinRange,
    const LPSYSTEMTIME pMaxRange);

Parameters

pMinRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the lowest end of the range.

pMaxRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the highest end of the range.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETRANGE, as described in the Windows SDK. In MFC's implementation of SetRange, you can specify COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

Example

See the example for CMonthCalCtrl::GetRange.

CMonthCalCtrl::SetSelRange

Sets the selection for a month calendar control to a given date range.

BOOL SetSelRange(
    const COleDateTime& pMinRange,
    const COleDateTime& pMaxRange);

BOOL SetSelRange(
    const CTime& pMinRange,
    const CTime& pMaxRange);

BOOL SetSelRange(
    const LPSYSTEMTIME pMinRange,
    const LPSYSTEMTIME pMaxRange);

Parameters

pMinRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the lowest end of the range.

pMaxRange
A pointer to a COleDateTime object, a CTime object, or SYSTEMTIME structure containing the date at the highest end of the range.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message MCM_SETSELRANGE, as described in the Windows SDK. In MFC's implementation of SetSelRange, you can specify COleDateTime usage, a CTime usage, or a SYSTEMTIME structure usage.

CMonthCalCtrl::SetToday

Sets the calendar control for the current day.

void SetToday(const COleDateTime& refDateTime);
void SetToday(const CTime* pDateTime);
void SetToday(const LPSYSTEMTIME pDateTime);

Parameters

refDateTime
A reference to a COleDateTime object that contains the current date.

pDateTime
In the second version, a pointer to a CTime object containing the current date information. In the third version, a pointer to a SYSTEMTIME structure that contains the current date information.

Remarks

This member function implements the behavior of the Win32 message MCM_SETTODAY, as described in the Windows SDK.

Example

See the example for CMonthCalCtrl::GetToday.

CMonthCalCtrl::SetYearView

Sets the current month calendar control to year view.

BOOL SetYearView();

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method uses the CMonthCalCtrl::SetCurrentView method to set the view to MCMV_YEAR, which represents the annual view.

CMonthCalCtrl::SizeMinReq

Displays the month calendar control to the minimum size that displays one month.

BOOL SizeMinReq(BOOL bRepaint = TRUE);

Parameters

bRepaint
Specifies whether the control is to be repainted. By default, TRUE. If FALSE, no repainting occurs.

Return Value

Nonzero if the month calendar control is sized to its minimum; otherwise 0.

Remarks

Calling SizeMinReq successfully displays the entire month calendar control for one month's calendar.

CMonthCalCtrl::SizeRectToMin

For the current month calendar control, calculates the smallest rectangle that can contain all the calendars that fit in a specified rectangle.

LPRECT SizeRectToMin(LPRECT lpRect);

Parameters

lpRect
[in] Pointer to a RECT structure that defines a rectangle that contains the desired number of calendars.

Return Value

Pointer to a RECT structure that defines a rectangle whose size is less than or equal to the rectangle defined by the lpRect parameter.

Remarks

This method calculates how many calendars can fit in the rectangle specified by the lpRect parameter, and then returns the smallest rectangle that can contain that number of calendars. In effect, this method shrinks the specified rectangle to exactly fit the desired number of calendars.

This method sends the MCM_SIZERECTTOMIN message, which is described in the Windows SDK.