Classe CDateTimeCtrl

Encapsula a funcionalidade de um controle seletor de data e hora.

Sintaxe

class CDateTimeCtrl : public CWnd

Membros

Construtores públicos

Métodos públicos

Comentários

O controle de seletor de data e hora (controle DTP) fornece uma interface simples para trocar informações de data e hora com um usuário. Essa interface contém campos, cada um dos quais exibe uma parte das informações de data e hora armazenadas no controle. O usuário pode alterar as informações armazenadas no controle alterando o conteúdo da cadeia de caracteres em um determinado campo. O usuário pode mover de campo em campo usando o mouse ou o teclado.

Você pode personalizar o controle de seletor de data e hora aplicando uma variedade de estilos ao objeto ao criá-lo. Confira Estilos de controle seletor de data e hora no SDK do Windows para mais informações sobre estilos específicos para o controle de seletor de data e hora. Você pode definir o formato de exibição do controle DTP usando estilos de formato. Esses estilos de formato são descritos em "Estilos de Formato" no tópico Estilos de controle de seletor de data e hora do SDK do Windows.

O controle do seletor de data e hora também usa notificações e retornos de chamada, que são descritos em Como usar CDateTimeCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CDateTimeCtrl

Requisitos

Cabeçalho: afxdtctl.h

CDateTimeCtrl::CDateTimeCtrl

Constrói um objeto CDateTimeCtrl.

CDateTimeCtrl();

CDateTimeCtrl::CloseMonthCal

Fecha o controle de seletor de data e hora atual.

void CloseMonthCal() const;

Comentários

Esse método envia a mensagem DTM_CLOSEMONTHCAL, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_dateTimeCtrl, que é usada para acessar programaticamente o controle de seletor de data e hora. Essa variável será usada no próximo exemplo.

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

O próximo exemplo de código fecha o calendário suspenso para o controle de seletor de data e hora atual.

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

CDateTimeCtrl::Create

Cria o controle seletor de data e hora e o anexa ao objeto CDateTimeCtrl.

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

Parâmetros

dwStyle
Especifica a combinação de estilos de controle de data e hora. Confira Estilos de controle seletor de data e hora no SDK do Windows para mais informações sobre estilos de seletor de data e hora.

rect
Uma referência a uma estrutura RECT, que é a posição e o tamanho do controle de seletor de data e hora.

pParentWnd
Um ponteiro para um objeto CWnd que é a janela pai do controle do seletor de data e hora. Não deve ser NULL.

nID
Especifica a ID de controle referente ao controle do seletor de data e hora.

Valor de retorno

Não zero se a criação foi bem-sucedida; caso contrário, 0.

Comentários

Para criar um controle de seletor de data e hora

1. Chame CDateTimeCtrl para construir um objeto CDateTimeCtrl.

2. Chame essa função de membro, que cria o controle seletor de data e hora do Windows e o anexa ao objeto CDateTimeCtrl.

Quando você chama Create, os controles comuns são inicializados.

Exemplo

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

Recupera informações sobre o controle de seletor de data e hora atual.

BOOL GetDateTimePickerInfo(LPDATETIMEPICKERINFO pDateTimePickerInfo) const;

Parâmetros

pDateTimePickerInfo
[out] Um ponteiro para uma estrutura DATETIMEPICKERINFO que recebe uma descrição do controle de seletor de data e hora atual. O chamador é responsável por alocar essa estrutura. No entanto, esse método inicializa o membro cbSize da estrutura.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem DTM_GETDATETIMEPICKERINFO, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_dateTimeCtrl, que é usada para acessar programaticamente o controle de seletor de data e hora. Essa variável será usada no próximo exemplo.

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

O próximo exemplo de código indica se ele recupera com êxito informações sobre o controle de seletor de data e hora atual.

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

Recupera a cor de uma determinada parte do calendário do mês dentro do controle do seletor de data e hora.

COLORREF GetMonthCalColor(int iColor) const;

Parâmetros

iColor
Um valor int que especifica qual área de cor do calendário de mês a recuperar. Para uma lista de valores, confira o parâmetro iColor para SetMonthCalColor.

Valor de retorno

Um valor COLORREF que representa a configuração de cor para a parte especificada do controle de calendário do mês, se bem-sucedido. A função retornará -1 se não tiver êxito.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_GETMCCOLOR do Win32, conforme descrito no SDK do Windows.

Exemplo

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

Recupera o objeto CMonthCalCtrl associado ao controle de seletor de data e hora.

CMonthCalCtrl* GetMonthCalCtrl() const;

Valor de retorno

Um ponteiro para um objeto CMonthCalCtrl ou NULL se não tiver êxito ou se a janela não estiver visível.

Comentários

Os controles do seletor de data e hora criam um controle de calendário de mês filho quando o usuário seleciona a seta suspensa. Quando o objeto CMonthCalCtrl não for mais necessário, ele será destruído, portanto, seu aplicativo não deve depender de armazenar o objeto que representa o calendário do mês filho do controle de seletor de data e hora.

Exemplo

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

Obtém a fonte usada atualmente pelo controle de calendário de mês do controle de seletor de data e hora.

CFont* GetMonthCalFont() const;

Valor de retorno

Um ponteiro para um objeto CFont ou NULL se não tiver êxito.

Comentários

O objeto CFont apontado pelo valor retornado é um objeto temporário e é destruído durante o próximo tempo de processamento ocioso.

CDateTimeCtrl::GetMonthCalStyle

Obtém o estilo do controle de calendário de mês suspenso associado ao controle de seletor de data e hora atual.

DWORD GetMonthCalStyle() const;

Valor de retorno

O estilo do controle de calendário de mês suspenso, que é uma combinação bit a bit (OR) de estilos de controle de seletor de data e hora. Para mais informações, confira Estilos de controle de calendário de mês.

Comentários

Esse método envia a mensagem DTM_GETMCSTYLE, que é descrita no SDK do Windows.

CDateTimeCtrl::GetRange

Recupera as horas mínimas e máximas de sistema atuais permitidas para um controle de seletor de data e hora.

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

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

Parâmetros

pMinRange
Um ponteiro para um objeto COleDateTime ou um objeto CTime que contém o tempo mais antigo permitido no objeto CDateTimeCtrl.

pMaxRange
Um ponteiro para um objeto COleDateTime ou um objeto CTime que contém o tempo mais recente permitido no objeto CDateTimeCtrl.

Valor de retorno

Um valor DWORD que contém sinalizadores que indicam quais intervalos estão definidos. Se

return value & GDTR_MAX == 0

então o segundo parâmetro é válido. Da mesma forma, se

return value & GDTR_MIN == 0

então o primeiro parâmetro é válido.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_GETRANGE do Win32, conforme descrito no SDK do Windows. Na implementação do MFC, você pode especificar os usos COleDateTime ou CTime.

Exemplo

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

Recupera a hora selecionada no momento de um controle seletor de data e hora e o coloca em uma estrutura SYSTEMTIME especificada.

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

Parâmetros

timeDest
Na primeira versão, uma referência a um objeto COleDateTime que receberá as informações de hora do sistema. Na segunda versão, uma referência a um objeto CTime que receberá as informações de hora do sistema.

pTimeDest
Um ponteiro para a estrutura SYSTEMTIME para receber as informações de hora do sistema. Não deve ser NULL.

Valor de retorno

Na primeira versão, diferente de zero se a hora for gravada com êxito no objeto COleDateTime; caso contrário, 0. Na segunda e terceira versões, um valor DWORD igual ao membro dwFlag definido na estrutura NMDATETIMECHANGE. Confira a seção Comentários abaixo para obter mais informações.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_GETSYSTEMTIME do Win32, conforme descrito no SDK do Windows. Na implementação do MFC de GetTime, você pode usar classes COleDateTime ou CTime, ou você pode usar uma estrutura SYSTEMTIME, para armazenar as informações de tempo.

O valor retornado DWORD na segunda e terceira versões, acima, indica se o controle seletor de data e hora está ou não definido como o status "sem data", conforme indicado no membro dwFlags da estrutura NMDATETIMECHANGE. Se o valor retornado for igual a GDT_NONE, o controle será definido como status "sem data" e usará o estilo DTS_SHOWNONE. Se o valor retornado for igual a GDT_VALID, a hora do sistema será armazenada com êxito no local de destino.

Exemplo

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

Retorna o tamanho ideal do controle seletor de data e hora necessário para exibir a data ou hora atual.

BOOL GetIdealSize(LPSIZE psize) const;

Parâmetros

psize
[out] Ponteiro para uma estrutura SIZE que contém o tamanho ideal para o controle.

Valor de retorno

O valor retornado é sempre TRUE.

Comentários

Esse método envia a mensagem DTM_GETIDEALSIZE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_dateTimeCtrl, que é usada para acessar programaticamente o controle de seletor de data e hora. Essa variável será usada no próximo exemplo.

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

O próximo exemplo de código recupera o tamanho ideal para exibir o controle do seletor de data e hora.

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

Define a exibição de um controle seletor de data e hora de acordo com uma determinada cadeia de caracteres de formato.

BOOL SetFormat(LPCTSTR pstrFormat);

Parâmetros

pstrFormat
Um ponteiro para uma cadeia de caracteres de formato com término zero que define a exibição desejada. Definir esse parâmetro como NULL redefinirá o controle para a cadeia de caracteres de formato padrão para o estilo atual.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_SETFORMAT do Win32, conforme descrito no SDK do Windows.

Exemplo

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

Define a cor de uma determinada parte do calendário do mês em um controle de seletor de data e hora.

COLORREF SetMonthCalColor(
    int iColor,
    COLORREF ref);

Parâmetros

iColor
Valor int que especifica qual área do controle de calendário do mês definir. Este valor pode ser um dos a seguir.

ref
Um valor COLORREF que representa a cor que será definida para a área especificada do calendário do mês.

Valor de retorno

Um valor COLORREF que representa a configuração de cor anterior para a parte especificada do controle de calendário do mês, se bem-sucedido. Caso contrário, a mensagem retornará -1.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_SETMCCOLOR do Win32, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CDateTimeCtrl::GetMonthCalColor.

CDateTimeCtrl::SetMonthCalFont

Define a fonte que o controle de calendário do mês filho do controle de seletor de data e hora usará.

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

Parâmetros

hFont
Identificador para a fonte que será definida.

bRedraw
Especifica se o controle deve ser redesenhado imediatamente ao definir a fonte. Definir esse parâmetro como TRUE faz com que o controle seja redesenhado.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_SETMCFONT do Win32, conforme descrito no SDK do Windows.

Exemplo

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

CDateTimeCtrl::SetMonthCalStyle

Define o estilo do controle de calendário de mês suspenso associado ao controle de seletor de data e hora atual.

DWORD SetMonthCalStyle(DWORD dwStyle);

Parâmetros

dwStyle
[in] Um novo estilo de controle de calendário de mês, que é uma combinação bit a bit (OR) de estilos de controle de calendário de mês. Para mais informações, confira Estilos de controle de calendário de mês.

Valor de retorno

O estilo anterior do controle de calendário de mês suspenso.

Comentários

Esse método envia a mensagem DTM_SETMCSTYLE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_dateTimeCtrl, que é usada para acessar programaticamente o controle de seletor de data e hora. Essa variável será usada no próximo exemplo.

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

O próximo exemplo de código define o controle seletor de data e hora para exibir números de semana, nomes abreviados de dias da semana e nenhum indicador de hoje.

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

Define as horas mínimas e máximas permitidas do sistema para um controle de seletor de data e hora.

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

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

Parâmetros

pMinRange
Um ponteiro para um objeto COleDateTime ou um objeto CTime que contém o tempo mais antigo permitido no objeto CDateTimeCtrl.

pMaxRange
Um ponteiro para um objeto COleDateTime ou um objeto CTime que contém o tempo mais recente permitido no objeto CDateTimeCtrl.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_SETRANGE do Win32, conforme descrito no SDK do Windows. Na implementação do MFC, você pode especificar os usos COleDateTime ou CTime. Se o objeto COleDateTime tiver um status NULL, o intervalo será removido. Se o ponteiro CTime ou o ponteiro COleDateTime for NULL, o intervalo será removido.

Exemplo

Confira o exemplo de CDateTimeCtrl::GetRange.

CDateTimeCtrl::SetTime

Define a hora em um controle de seletor de data e hora.

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

Parâmetros

timeNew
Uma referência a um objeto COleDateTime que contém o valor para o qual o controle será definido.

pTimeNew
Na segunda versão acima, um ponteiro para um objeto CTime que contém a hora para a qual o controle será definido. Na terceira versão acima, um ponteiro para uma estrutura SYSTEMTIME que contém a hora para a qual o controle será definido.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função membro implementa o comportamento da mensagem DTM_SETSYSTEMTIME do Win32, conforme descrito no SDK do Windows. Na implementação do MFC de SetTime, você pode usar as classes COleDateTime ou CTime ou usar uma estrutura SYSTEMTIME para definir as informações de tempo.

Exemplo

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

Confira também

Exemplo de MFC CMNCTRL1
Classe CWnd
Gráfico da hierarquia
Classe CMonthCalCtrl