Edit

CDateTimeCtrl Class

  • Article

Encapsulates the functionality of a date and time picker control.

Syntax

class CDateTimeCtrl : public CWnd

Members

Public Constructors

Name Description
CDateTimeCtrl::CDateTimeCtrl Constructs a CDateTimeCtrl object.

Public Methods

Name Description
CDateTimeCtrl::CloseMonthCal Closes the current date and time picker control.
CDateTimeCtrl::Create Creates the date and time picker control and attaches it to the CDateTimeCtrl object.
CDateTimeCtrl::GetDateTimePickerInfo Retrieves information about the current date and time picker control.
CDateTimeCtrl::GetIdealSize Returns the ideal size of the date and time picker control that is required to display the current date or time.
CDateTimeCtrl::GetMonthCalColor Retrieves the color for a given portion of the month calendar within the date and time picker control.
CDateTimeCtrl::GetMonthCalCtrl Retrieves the CMonthCalCtrl object associated with the date and time picker control.
CDateTimeCtrl::GetMonthCalFont Retrieves the font currently used by the date and time picker control's child month calendar control.
CDateTimeCtrl::GetMonthCalStyle Gets the style of the current date and time picker control.
CDateTimeCtrl::GetRange Retrieves the current minimum and maximum allowed system times for a date and time picker control.
CDateTimeCtrl::GetTime Retrieves the currently selected time from a date and time picker control and puts it in a specified SYSTEMTIME structure.
CDateTimeCtrl::SetFormat Sets the display of a date and time picker control in accordance with a given format string.
CDateTimeCtrl::SetMonthCalColor Sets the color for a given portion of the month calendar within a date and time picker control.
CDateTimeCtrl::SetMonthCalFont Sets the font that the date and time picker control's child month calendar control will use.
CDateTimeCtrl::SetMonthCalStyle Sets the style of the current date and time picker control.
CDateTimeCtrl::SetRange Sets the minimum and maximum allowed system times for a date and time picker control.
CDateTimeCtrl::SetTime Sets the time in a date and time picker control.

Remarks

The date and time picker control (DTP control) provides a simple interface to exchange date and time information with a user. This interface contains fields, each of which displays a part of the date and time information stored in the control. The user can change the information stored in the control by changing the content of the string in a given field. The user can move from field to field using the mouse or the keyboard.

You can customize the date and time picker control by applying a variety of styles to the object when you create it. See Date and Time Picker Control Styles in the Windows SDK for more information about styles specific to the date and time picker control. You can set the display format of the DTP control using format styles. These format styles are described under "Format Styles" in the Windows SDK topic Date and Time Picker Control Styles.

The date and time picker control also uses notifications and callbacks, which are described in Using CDateTimeCtrl.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CDateTimeCtrl

Requirements

Header: afxdtctl.h

CDateTimeCtrl::CDateTimeCtrl

Constructs a CDateTimeCtrl object.

CDateTimeCtrl();

CDateTimeCtrl::CloseMonthCal

Closes the current date and time picker control.

void CloseMonthCal() const;

Remarks

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

Example

The first code example defines the variable, m_dateTimeCtrl, that is used to programmatically access the date and time picker control. This variable is used in the next example.

// Variable to access date-time control.
CDateTimeCtrl m_dateTimeCtrl;
// Variable to access the splitbutton control
CSplitButton m_splitbutton;

The next code example closes the drop-down calendar for the current date and time picker control.

void CCDateTimeCtrl_s1Dlg::OnXClosemonthcal()
{
   // Close the month calendar control dropdown.
   m_dateTimeCtrl.CloseMonthCal();
}

CDateTimeCtrl::Create

Creates the date and time picker control and attaches it to the CDateTimeCtrl object.

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

Parameters

dwStyle
Specifies the combination of date time control styles. See Date and Time Picker Control Styles in the Windows SDK for more information about date and time picker styles.

rect
A reference to a RECT structure, which is the position and size of the date and time picker control.

pParentWnd
A pointer to a CWnd object that is the parent window of the date and time picker control. It must not be NULL.

nID
Specifies the date and time picker control's control ID.

Return Value

Nonzero if creation was successful; otherwise 0.

Remarks

To create a date and time picker control

  1. Call CDateTimeCtrl to construct a CDateTimeCtrl object.

  2. Call this member function, which creates the Windows date and time picker control and attaches it to the CDateTimeCtrl object.

When you call Create, the common controls are initialized.

Example

// choose an arbitrary rectangle for creation
CRect rect(20, 20, 120, 45);
m_DateTimeCtrl.Create(WS_VISIBLE | WS_CHILD | WS_TABSTOP | DTS_SHOWNONE |
                          DTS_SHORTDATEFORMAT,
                      rect, this, IDC_DATETIMECTRL);

CDateTimeCtrl::GetDateTimePickerInfo

Retrieves information about the current date and time picker control.

BOOL GetDateTimePickerInfo(LPDATETIMEPICKERINFO pDateTimePickerInfo) const;

Parameters

pDateTimePickerInfo
[out] A pointer to a DATETIMEPICKERINFO structure that receives a description of the current date and time picker control. The caller is responsible for allocating this structure. However, this method initializes the cbSize member of the structure.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

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

Example

The first code example defines the variable, m_dateTimeCtrl, that is used to programmatically access the date and time picker control. This variable is used in the next example.

// Variable to access date-time control.
CDateTimeCtrl m_dateTimeCtrl;
// Variable to access the splitbutton control
CSplitButton m_splitbutton;

The next code example indicates whether it successfully retrieves information about the current date and time picker control.

void CCDateTimeCtrl_s1Dlg::OnXGetdatetimepickerinfo()
{
   // Get information about the date-time picker control.
   DATETIMEPICKERINFO dtpi = {0};
   dtpi.cbSize = sizeof(DATETIMEPICKERINFO);
   BOOL rc = m_dateTimeCtrl.GetDateTimePickerInfo(&dtpi);
   if (rc == TRUE)
      AfxMessageBox(_T("Information retrieved"),
                    MB_ICONEXCLAMATION);
   else
      AfxMessageBox(_T("Information was not retrieved"));
}

CDateTimeCtrl::GetMonthCalColor

Retrieves the color for a given portion of the month calendar within the date and time picker control.

COLORREF GetMonthCalColor(int iColor) const;

Parameters

iColor
An int value specifying which color area of the month calendar to retrieve. For a list of values, see the iColor parameter for SetMonthCalColor.

Return Value

A COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. The function returns -1 if unsuccessful.

Remarks

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

Example

// Set the color for the text in the control and
// assure it was set properly. Unlike the GetMonthCalCtrl() member,
// GetMonthCalColor() and SetMonthCalColor() can be used at any time.
m_DateTimeCtrl.SetMonthCalColor(MCSC_TEXT, RGB(255, 0, 0));
VERIFY(m_DateTimeCtrl.GetMonthCalColor(MCSC_TEXT) == RGB(255, 0, 0));

CDateTimeCtrl::GetMonthCalCtrl

Retrieves the CMonthCalCtrl object associated with the date and time picker control.

CMonthCalCtrl* GetMonthCalCtrl() const;

Return Value

A pointer to a CMonthCalCtrl object, or NULL if unsuccessful or if the window isn't visible.

Remarks

Date and time picker controls create a child month calendar control when the user selects the drop-down arrow. When the CMonthCalCtrl object is no longer needed, it's destroyed, so your application must not rely on storing the object representing the date time picker control's child month calendar.

Example

void CDateTimeDlg::OnDropDownDateTimeCtrl(NMHDR *pNMHDR, LRESULT *pResult)
{
   UNREFERENCED_PARAMETER(pNMHDR);

   // note that GetMonthCalCtrl() will only return a pointer to the
   // month calendar control while the control actually exists--that is,
   // while it has been dropped-down by the user. Otherwise, the function
   // returns NULL. One appropriate time to get the control is while
   // handling the DTN_DROPDOWN notification for the date time picker
   // control.

   // get the control
   CMonthCalCtrl *pMoCalCtrl = m_DateTimeCtrl.GetMonthCalCtrl();
   ASSERT(pMoCalCtrl != NULL);

   // now, pMoCalCtrl is useful...

   *pResult = 0;
}

CDateTimeCtrl::GetMonthCalFont

Gets the font currently used by the date and time picker control's month calendar control.

CFont* GetMonthCalFont() const;

Return Value

A pointer to a CFont object, or NULL if unsuccessful.

Remarks

The CFont object pointed to by the return value is a temporary object and is destroyed during the next idle processing time.

CDateTimeCtrl::GetMonthCalStyle

Gets the style of the drop-down month calendar control that is associated with the current date and time picker control.

DWORD GetMonthCalStyle() const;

Return Value

The style of the drop-down month calendar control, which is a bitwise combination (OR) of date and time picker control styles. For more information, see Month Calendar Control Styles.

Remarks

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

CDateTimeCtrl::GetRange

Retrieves the current minimum and maximum allowed system times for a date and time picker control.

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

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

Parameters

pMinRange
A pointer to a COleDateTime object or a CTime object containing the earliest time allowed in the CDateTimeCtrl object.

pMaxRange
A pointer to a COleDateTime object or a CTime object containing the latest time allowed in the CDateTimeCtrl object.

Return Value

A DWORD value containing flags that indicate which ranges are set. If

return value & GDTR_MAX == 0

then the second parameter is valid. Similarly, if

return value & GDTR_MIN == 0

then the first parameter is valid.

Remarks

This member function implements the behavior of the Win32 message DTM_GETRANGE, as described in the Windows SDK. In MFC's implementation, you can specify either COleDateTime or CTime usages.

Example

// This function will set several ranges in the control, then
// call the ShowRange() function to show the set ranges to the
// user.
void CDateTimeDlg::OnBnClickedRangesbutton()
{
   // 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_DateTimeCtrl.SetRange(&dtMin, &dtMax);
   ShowRange(&m_DateTimeCtrl);

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

   // 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_DateTimeCtrl.SetRange(&dtMin, &dtMax);
   ShowRange(&m_DateTimeCtrl);
}

void CDateTimeDlg::ShowRange(CDateTimeCtrl *pCtrl)
{
   ASSERT(pCtrl != NULL);
   CString strMessage;
   COleDateTime dtMinimum;
   COleDateTime dtMaximum;

   // Get the range.
   DWORD dwResult = pCtrl->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);
}

CDateTimeCtrl::GetTime

Retrieves the currently selected time from a date and time picker control and puts it in a specified SYSTEMTIME structure.

BOOL GetTime(COleDateTime& timeDest) const;
DWORD GetTime(CTime& timeDest) const;
DWORD GetTime(LPSYSTEMTIME pTimeDest) const;

Parameters

timeDest
In the first version, a reference to a COleDateTime object that will receive the system time information. In the second version, a reference to a CTime object that will receive the system time information.

pTimeDest
A pointer to the SYSTEMTIME structure to receive the system time information. Must not be NULL.

Return Value

In the first version, nonzero if the time is successfully written to the COleDateTime object; otherwise 0. In the second and third versions, a DWORD value equal to the dwFlag member set in the NMDATETIMECHANGE structure. See the Remarks section below for more information.

Remarks

This member function implements the behavior of the Win32 message DTM_GETSYSTEMTIME, as described in the Windows SDK. In the MFC implementation of GetTime, you can use COleDateTime or CTime classes, or you can use a SYSTEMTIME structure, to store the time information.

The return value DWORD in the second and third versions, above, indicates whether or not the date and time picker control is set to the "no date" status, as indicated in the NMDATETIMECHANGE structure member dwFlags. If the value returned equals GDT_NONE, the control is set to "no date" status, and uses the DTS_SHOWNONE style. If the value returned equals GDT_VALID, the system time is successfully stored in the destination location.

Example

void CDateTimeDlg::OnBnClickedTimebutton()
{
   // get as a CTime
   CTime timeTime;
   DWORD dwResult = m_DateTimeCtrl.GetTime(timeTime);
   if (dwResult == GDT_VALID)
   {
      // the user checked the box and specified data
      CString str;

      // is it a time-only control, or a date-only control?
      if ((m_DateTimeCtrl.GetStyle() & DTS_TIMEFORMAT) == DTS_TIMEFORMAT)
         str = timeTime.Format(_T("%X"));
      else
         str = timeTime.Format(_T("%x"));
      AfxMessageBox(str);
   }
   else
   {
      // the user unmarked the "none" box
      AfxMessageBox(_T("Time not set!"));
   }

   // Calling as SYSTIME is much the same, but calling for a COleDateTime
   // has us test the state of the COleDateTime object for validity to
   // see if the user did or didn't check the "none" box.
}

CDateTimeCtrl::GetIdealSize

Returns the ideal size of the date and time picker control that is required to display the current date or time.

BOOL GetIdealSize(LPSIZE psize) const;

Parameters

psize
[out] Pointer to a SIZE structure that contains the ideal size for the control.

Return Value

The return value is always TRUE.

Remarks

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

Example

The first code example defines the variable, m_dateTimeCtrl, that is used to programmatically access the date and time picker control. This variable is used in the next example.

// Variable to access date-time control.
CDateTimeCtrl m_dateTimeCtrl;
// Variable to access the splitbutton control
CSplitButton m_splitbutton;

The next code example retrieves the ideal size to display the date and time picker control.

// Add extra initialization here

// Associate a menu with the splitbutton control.
m_splitbutton.SetDropDownMenu(IDR_MENU1, 0);

// Resize the date-time picker control.
SIZE sz;
m_dateTimeCtrl.GetIdealSize(&sz);
if ((sz.cx != 0) && (sz.cy != 0))
{
   m_dateTimeCtrl.SetWindowPos(
       this,
       0, 0, sz.cx, sz.cy,
       (SWP_NOMOVE | SWP_NOZORDER | SWP_NOREPOSITION | SWP_NOACTIVATE));
}

// End of extra initialization

CDateTimeCtrl::SetFormat

Sets the display of a date and time picker control in accordance with a given format string.

BOOL SetFormat(LPCTSTR pstrFormat);

Parameters

pstrFormat
A pointer to a zero-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style.

Return Value

Nonzero if successful; otherwise 0.

Note

User input does not determine success or failure for this call.

Remarks

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

Example

// The control will create itself with a format that matches the
// locale setting in Control Panel. But we can force a particular
// format with a call to SetFormat(). This call forces the format
// dd-MMM-yy, which would show 03-APR-98 for April 3rd, 1998.
m_DateTimeCtrl.SetFormat(_T("dd-MMM-yy"));

CDateTimeCtrl::SetMonthCalColor

Sets the color for a given portion of the month calendar within a date and time picker control.

COLORREF SetMonthCalColor(
    int iColor,
    COLORREF ref);

Parameters

iColor
int value specifying which area of the month calendar control to set. This value can be one of the following.

Value Meaning
MCSC_BACKGROUND Set the background color displayed between months.
MCSC_MONTHBK Set the background color displayed within a month.
MCSC_TEXT Set the color used to display text within a month.
MCSC_TITLEBK Set the background color displayed in the calendar's title.
MCSC_TITLETEXT Set the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT Set 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 representing the color that will be set for the specified area of the month calendar.

Return Value

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

Remarks

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

Example

See the example for CDateTimeCtrl::GetMonthCalColor.

CDateTimeCtrl::SetMonthCalFont

Sets the font that the date and time picker control's child month calendar control will use.

void SetMonthCalFont(
    HFONT hFont,
    BOOL bRedraw = TRUE);

Parameters

hFont
Handle to the font that will be set.

bRedraw
Specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to TRUE causes the control to redraw itself.

Remarks

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

Example

// The following code example would most likely appear
// in the OnInitDialog function of your dialog class.
// It creates a font (Arial, 10 pixels high) and if successful,
// stores the result in m_MonthFont, a member of your
// dialog class declared as follows:
//    CFont m_MonthFont;
// SetMonthCalFont is then called passing in the new font,
// causing the month calendar control to display all
// text and dates with an Arial font.

//initializing the necessary members of the LOGFONT
// structure

LOGFONT lf;
memset(&lf, 0, sizeof(lf));
lf.lfHeight = 10;
_tcscpy_s(lf.lfFaceName, LF_FACESIZE, _T("Arial"));

if (m_MonthFont.CreateFontIndirect(&lf))
{
   // if successful, set the month calendar font
   m_DateTimeCtrl.SetMonthCalFont((HFONT)m_MonthFont);
}

Note

If you use this code, you'll want to make a member of your CDialog-derived class called m_MonthFont of type CFont.

CDateTimeCtrl::SetMonthCalStyle

Sets the style of the drop-down month calendar control that is associated with the current date and time picker control.

DWORD SetMonthCalStyle(DWORD dwStyle);

Parameters

dwStyle
[in] A new month calendar control style, which is a bitwise combination (OR) of month calendar control styles. For more information, see Month Calendar Control Styles.

Return Value

The previous style of the drop-down month calendar control.

Remarks

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

Example

The first code example defines the variable, m_dateTimeCtrl, that is used to programmatically access the date and time picker control. This variable is used in the next example.

// Variable to access date-time control.
CDateTimeCtrl m_dateTimeCtrl;
// Variable to access the splitbutton control
CSplitButton m_splitbutton;

The next code example sets the date and time picker control to display week numbers, abbreviated names of days of the week, and no today indicator.

// Set the style of the month-calendar control dropdown.
void CCDateTimeCtrl_s1Dlg::OnSetmonthcalstyleWeeknumber()
{
   m_dateTimeCtrl.SetMonthCalStyle(MCS_WEEKNUMBERS);
}

void CCDateTimeCtrl_s1Dlg::OnSetmonthcalstyleNotoday()
{
   m_dateTimeCtrl.SetMonthCalStyle(MCS_NOTODAY);
}

void CCDateTimeCtrl_s1Dlg::OnSetmonthcalstyleShortdaysofweek()
{
   m_dateTimeCtrl.SetMonthCalStyle(MCS_SHORTDAYSOFWEEK);
}

CDateTimeCtrl::SetRange

Sets the minimum and maximum allowed system times for a date and time picker control.

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

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

Parameters

pMinRange
A pointer to a COleDateTime object or a CTime object containing the earliest time allowed in the CDateTimeCtrl object.

pMaxRange
A pointer to a COleDateTime object or a CTime object containing the latest time allowed in the CDateTimeCtrl object.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message DTM_SETRANGE, as described in the Windows SDK. In MFC's implementation, you can specify either COleDateTime or CTime usages. If the COleDateTime object has a NULL status, the range will be removed. If the CTime pointer or the COleDateTime pointer is NULL, the range will be removed.

Example

See the example for CDateTimeCtrl::GetRange.

CDateTimeCtrl::SetTime

Sets the time in a date and time picker control.

BOOL SetTime(const COleDateTime& timeNew);
BOOL SetTime(const CTime* pTimeNew);
BOOL SetTime(LPSYSTEMTIME pTimeNew = NULL);

Parameters

timeNew
A reference to a COleDateTime object containing the to which the control will be set.

pTimeNew
In the second version above, a pointer to a CTime object containing the time to which the control will be set. In the third version above, a pointer to a SYSTEMTIME structure containing the time to which the control will be set.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message DTM_SETSYSTEMTIME, as described in the Windows SDK. In the MFC implementation of SetTime, you can use the COleDateTime or CTime classes, or you can use a SYSTEMTIME structure, to set the time information.

Example

// set with a CTime
CTime timeTime(1998, 4, 3, 0, 0, 0);
VERIFY(m_DateTimeCtrl.SetTime(&timeTime));

// set with a COleDateTime object
COleDateTime oletimeTime(1998, 4, 3, 0, 0, 0);
VERIFY(m_DateTimeCtrl.SetTime(oletimeTime));

// set using the SYSTEMTIME
SYSTEMTIME sysTime;
memset(&sysTime, 0, sizeof(sysTime));
sysTime.wYear = 1998;
sysTime.wMonth = 4;
sysTime.wDay = 3;
VERIFY(m_DateTimeCtrl.SetTime(&sysTime));

See also

MFC Sample CMNCTRL1
CWnd Class
Hierarchy Chart
CMonthCalCtrl Class