CDateTimeCtrl Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CDateTimeCtrl Class.
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
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 following 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;
Example
The following 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
Call CDateTimeCtrl to construct a
CDateTimeCtrl
object.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
Parameter | Description |
---|---|
[out] pDateTimePickerInfo |
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 following 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;
Example
The following 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 is not visible.
Remarks
Date and time picker controls create a child month calendar control when the user clicks the drop-down arrow. When the CMonthCalCtrl
object is no longer needed, it is 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
Parameter | Description |
---|---|
[out] psize |
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 following 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;
Example
The following 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
Parameter | Description |
---|---|
[in] dwStyle |
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 following 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;
Example
The following 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