CDateTimeCtrl

封装日期和时间选取器控件功能。

语法

class CDateTimeCtrl : public CWnd

成员

公共构造函数

名称 描述
CDateTimeCtrl::CDateTimeCtrl 构造 CDateTimeCtrl 对象。

公共方法

名称 描述
CDateTimeCtrl::CloseMonthCal 关闭当前日期和时间选取器控件。
CDateTimeCtrl::Create 创建日期和时间选取器控件并将其附加到 CDateTimeCtrl 对象。
CDateTimeCtrl::GetDateTimePickerInfo 检索有关当前日期和时间选取器控件的信息。
CDateTimeCtrl::GetIdealSize 返回显示当前日期或时间所需的日期和时间选取器控件的理想大小。
CDateTimeCtrl::GetMonthCalColor 在日期和时间选取器控件中检索月历给定部分的颜色。
CDateTimeCtrl::GetMonthCalCtrl 检索与日期和时间选取器控件关联的 CMonthCalCtrl 对象。
CDateTimeCtrl::GetMonthCalFont 检索日期和时间选取器控件的子月历控件当前使用的字体。
CDateTimeCtrl::GetMonthCalStyle 获取当前日期和时间选取器控件的样式。
CDateTimeCtrl::GetRange 检索日期和时间选取器控件当前允许的最小和最大系统时间。
CDateTimeCtrl::GetTime 从日期和时间选取器控件中检索当前选定的时间并将其放入指定的 SYSTEMTIME 结构中。
CDateTimeCtrl::SetFormat 根据给定的格式字符串设置日期和时间选取器控件的显示。
CDateTimeCtrl::SetMonthCalColor 在日期和时间选取器控件中设置月历给定部分的颜色。
CDateTimeCtrl::SetMonthCalFont 设置日期和时间选取器控件的子月历控件将使用的字体。
CDateTimeCtrl::SetMonthCalStyle 设置当前日期和时间选取器控件的样式。
CDateTimeCtrl::SetRange 为日期和时间选取器控件设置允许的最小和最大系统时间。
CDateTimeCtrl::SetTime 在日期和时间选取器控件中设置时间。

注解

日期和时间选取器控件(DTP 控件)提供了一个简单的界面,用于与用户交换日期和时间信息。 该界面包含字段,每个字段显示控件中存储的部分日期和时间信息。 用户可以通过更改给定字段中字符串的内容来更改控件中存储的信息。 用户可以使用鼠标或键盘从一个字段移动到另一个字段。

可以通过在创建对象时将各种样式应用于对象来自定义日期和时间选取器控件。 有关特定于日期和时间选取器控件的样式的详细信息,请参阅 Windows SDK 中的日期和时间选取器控件样式。 可以使用格式样式设置 DTP 控件的显示格式。 Windows SDK 主题日期和时间选取器控件样式中的“格式样式”介绍了这些格式样式。

日期和时间选取器控件还使用通知和回调,如使用 CDateTimeCtrl 中所述。

继承层次结构

CObject

CCmdTarget

CWnd

CDateTimeCtrl

要求

标头afxdtctl.h

CDateTimeCtrl::CDateTimeCtrl

构造 CDateTimeCtrl 对象。

CDateTimeCtrl();

CDateTimeCtrl::CloseMonthCal

关闭当前日期和时间选取器控件。

void CloseMonthCal() const;

注解

此方法将发送 DTM_CLOSEMONTHCAL 消息,如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_dateTimeCtrl,用于以编程方式访问日期和时间选取器控件。 此变量将在下一个示例中使用。

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

下一个代码示例关闭当前日期和时间选取器控件的下拉日历。

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

CDateTimeCtrl::Create

创建日期和时间选取器控件并将其附加到 CDateTimeCtrl 对象。

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

参数

dwStyle
指定日期时间控件样式的组合。 有关日期和时间选取器样式的详细信息,请参阅 Windows SDK 中的日期和时间选取器控件样式

rect
RECT 结构(即日期和时间选取器控件的位置和大小)的引用。

pParentWnd
指向 CWnd 对象的指针,该对象是日期和时间选取器控件的父窗口。 不得为 NULL

nID
指定日期和时间选取器控件的控件 ID。

返回值

如果创建成功,则为非零值;否则为 0。

注解

创建日期和时间选取器控件
  1. 调用 CDateTimeCtrl 以构造 CDateTimeCtrl 对象。

  2. 调用此成员函数,创建 Windows 日期和时间选取器控件并将其附加到 CDateTimeCtrl 对象。

调用 Create 时,会初始化公用控件。

示例

// 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

检索有关当前日期和时间选取器控件的信息。

BOOL GetDateTimePickerInfo(LPDATETIMEPICKERINFO pDateTimePickerInfo) const;

参数

pDateTimePickerInfo
[输出] 指向 DATETIMEPICKERINFO 结构的指针,该结构接收当前日期和时间选取器控件的说明。 调用方负责分配此结构。 但是,此方法初始化结构的 cbSize 成员。

返回值

如果此方法成功,则为 TRUE;否则为 FALSE

注解

此方法将发送 DTM_GETDATETIMEPICKERINFO 消息,如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_dateTimeCtrl,用于以编程方式访问日期和时间选取器控件。 此变量将在下一个示例中使用。

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

下一个代码示例指示它是否成功检索有关当前日期和时间选取器控件的信息。

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

在日期和时间选取器控件中检索月历给定部分的颜色。

COLORREF GetMonthCalColor(int iColor) const;

参数

iColor
一个 int 值,指定要检索的月份日历的颜色区域。 有关值的列表,请参阅 SetMonthCalColoriColor 参数。

返回值

如果成功,则返回一个 COLORREF 值,表示月历控件中指定部分的颜色设置。 如果不成功,该函数返回 -1。

备注

此成员函数实现 Win32 消息 DTM_GETMCCOLOR 的行为,如 Windows SDK 中所述。

示例

// 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

检索与日期和时间选取器控件关联的 CMonthCalCtrl 对象。

CMonthCalCtrl* GetMonthCalCtrl() const;

返回值

指向 CMonthCalCtrl 对象的指针,如果不成功或窗口不可见,则为 NULL

备注

当用户选择下拉箭头时,日期和时间选取器控件会创建一个子月历控件。 不再需要 CMonthCalCtrl 对象时,它会被销毁,因此应用程序不能依赖存储表示日期时间选取器控件的子月历的对象。

示例

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

获取日期和时间选取器控件的月历控件当前使用的字体。

CFont* GetMonthCalFont() const;

返回值

指向 CFont 对象的指针,如果不成功,则为 NULL

备注

返回值指向的 CFont 对象是临时对象,会在下一个空闲处理时间销毁。

CDateTimeCtrl::GetMonthCalStyle

获取与当前日期和时间选取器控件关联的下拉月历控件的样式。

DWORD GetMonthCalStyle() const;

返回值

下拉月历控件的样式,它是日期和时间选取器控件样式的按位组合 (OR)。 有关详细信息,请参阅月历控件样式

注解

此方法将发送 DTM_GETMCSTYLE 消息,如 Windows SDK 中所述。

CDateTimeCtrl::GetRange

检索日期和时间选取器控件当前允许的最小和最大系统时间。

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

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

参数

pMinRange
指向 COleDateTime 对象或 CTime 对象的指针,包含 CDateTimeCtrl 对象中允许的最早时间。

pMaxRange
指向 COleDateTime 对象或 CTime 对象的指针,包含 CDateTimeCtrl 对象中允许的最晚时间。

返回值

一个 DWORD 值,包含指示设置了哪些范围的标志。 If

return value & GDTR_MAX == 0

那么第二个参数有效。 同样,如果

return value & GDTR_MIN == 0

那么第一个参数有效。

备注

此成员函数实现 Win32 消息 DTM_GETRANGE 的行为,如 Windows SDK 中所述。 在 MFC 的实现中,可以指定 COleDateTimeCTime 用法。

示例

// 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

从日期和时间选取器控件中检索当前选定的时间并将其放入指定的 SYSTEMTIME 结构中。

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

参数

timeDest
在第一个版本中,对将接收系统时间信息的 COleDateTime 对象的引用。 在第二个版本中,对将接收系统时间信息的 CTime 对象的引用。

pTimeDest
指向 SYSTEMTIME 结构的指针,用于接收系统时间信息。 不得为 NULL

返回值

在第一个版本中,如果时间成功写入 COleDateTime 对象,则非零;否则为 0。 在第二个和第三个版本中,DWORD 值等于 NMDATETIMECHANGE 结构中的 dwFlag 成员集。 有关详细信息,请参阅下面的备注部分

备注

此成员函数实现 Win32 消息 DTM_GETSYSTEMTIME 的行为,如 Windows SDK 中所述。 在 GetTime 的 MFC 实现中,可以使用 COleDateTimeCTime 类,也可以使用 SYSTEMTIME 结构来存储时间信息。

上面第二个和第三个版本中的返回值 DWORD 指示日期和时间选取器控件是否设置为“无日期”状态,如 NMDATETIMECHANGE 结构成员 dwFlags 所示。 如果返回值等于 GDT_NONE,则控件设置为“无日期”状态,并使用 DTS_SHOWNONE 样式。 如果返回值等于 GDT_VALID,系统时间就成功存储在目标位置。

示例

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

返回显示当前日期或时间所需的日期和时间选取器控件的理想大小。

BOOL GetIdealSize(LPSIZE psize) const;

参数

psize
[输出] 指向包含控件理想大小的 SIZE 结构的指针。

返回值

返回值始终为 TRUE

备注

此方法将发送 DTM_GETIDEALSIZE 消息,如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_dateTimeCtrl,用于以编程方式访问日期和时间选取器控件。 此变量将在下一个示例中使用。

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

下一个代码示例检索理想大小以显示日期和时间选取器控件。

// 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

根据给定的格式字符串设置日期和时间选取器控件的显示。

BOOL SetFormat(LPCTSTR pstrFormat);

参数

pstrFormat
指向定义所需显示的以零结尾的格式字符串的指针。 将此参数设置为 NULL 会将控件重置为当前样式的默认格式字符串。

返回值

如果成功,则不为 0;否则为 0。

注意

用户输入不决定此调用的成功或失败。

备注

此成员函数实现 Win32 消息 DTM_SETFORMAT 的行为,如 Windows SDK 中所述。

示例

// 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

在日期和时间选取器控件中设置月历给定部分的颜色。

COLORREF SetMonthCalColor(
    int iColor,
    COLORREF ref);

参数

iColor
int 值,指定要设置的月历控件区域。 此值可为下列值之一。

含义
MCSC_BACKGROUND 设置月份之间显示的背景色。
MCSC_MONTHBK 设置月份中显示的背景色。
MCSC_TEXT 设置用于显示月份中文本的颜色。
MCSC_TITLEBK 设置日历标题中显示的背景色。
MCSC_TITLETEXT 设置用于显示日历标题中的文本的颜色。
MCSC_TRAILINGTEXT 设置用于显示前置和后置天数文本的颜色。 前置和后置天数是指与当前日历上显示的上一个月和下一个月相距的天数。

ref
一个 COLORREF 值,表示将为月历的指定区域设置的颜色。

返回值

如果成功,则返回一个 COLORREF 值,表示月历控件中指定部分的先前颜色设置。 否则,此消息返回 -1。

备注

此成员函数实现 Win32 消息 DTM_SETMCCOLOR 的行为,如 Windows SDK 中所述。

示例

请参阅 CDateTimeCtrl::GetMonthCalColor 的示例。

CDateTimeCtrl::SetMonthCalFont

设置日期和时间选取器控件的子月历控件将使用的字体。

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

参数

hFont
要设置的字体的句柄。

bRedraw
指定是否应在设置字体后立即重绘控件。 将此参数设置为 TRUE 会导致控件重绘自身。

备注

此成员函数实现 Win32 消息 DTM_SETMCFONT 的行为,如 Windows SDK 中所述。

示例

// 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);
}

注意

如果使用此代码,需要创建名为 m_MonthFont 的 CDialog 派生类的成员,类型为 CFont

CDateTimeCtrl::SetMonthCalStyle

设置与当前日期和时间选取器控件关联的下拉月历控件的样式。

DWORD SetMonthCalStyle(DWORD dwStyle);

参数

dwStyle
[输入] 新的月历控件样式,它是月历控件样式的按位组合 (OR)。 有关详细信息,请参阅月历控件样式

返回值

下拉月历控件以前的样式。

注解

此方法将发送 DTM_SETMCSTYLE 消息,如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_dateTimeCtrl,用于以编程方式访问日期和时间选取器控件。 此变量将在下一个示例中使用。

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

下一个代码示例将日期和时间选取器控件设置为显示周数、星期几的缩写名称,且不显示今天指示器。

// 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

为日期和时间选取器控件设置允许的最小和最大系统时间。

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

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

参数

pMinRange
指向 COleDateTime 对象或 CTime 对象的指针,包含 CDateTimeCtrl 对象中允许的最早时间。

pMaxRange
指向 COleDateTime 对象或 CTime 对象的指针,包含 CDateTimeCtrl 对象中允许的最晚时间。

返回值

如果成功,则不为 0;否则为 0。

备注

此成员函数实现 Win32 消息 DTM_SETRANGE 的行为,如 Windows SDK 中所述。 在 MFC 的实现中,可以指定 COleDateTimeCTime 用法。 如果 COleDateTime 对象状态为 NULL,则范围将被删除。 如果 CTime 指针或 COleDateTime 指针为 NULL,则范围将被删除。

示例

请参阅 CDateTimeCtrl::GetRange 的示例。

CDateTimeCtrl::SetTime

在日期和时间选取器控件中设置时间。

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

参数

timeNew
对包含将设置控件的 COleDateTime 对象的引用。

pTimeNew
在上面的第二个版本中,指向包含控件设置时间的 CTime 对象的指针。 在上面的第三个版本中,指向 SYSTEMTIME 结构的指针,其中包含将设置控件的时间。

返回值

如果成功,则不为 0;否则为 0。

备注

此成员函数实现 Win32 消息 DTM_SETSYSTEMTIME 的行为,如 Windows SDK 中所述。 在 SetTime 的 MFC 实现中,可以使用 COleDateTimeCTime 类,也可以使用 SYSTEMTIME 结构来设置时间信息。

示例

// 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));

另请参阅

MFC 示例 CMNCTRL1
CWnd
层次结构图
CMonthCalCtrl