Share via

Sobre controles de seletor de data e hora

  • Artigo

Um controle DTP (seletor de data e hora) fornece uma interface simples e intuitiva por meio da qual é possível trocar informações de data e hora com um usuário. Por exemplo, com um controle DTP, você pode pedir ao usuário para inserir uma data e, em seguida, recuperar facilmente a seleção.

Os seguintes tópicos são abordados:

Observação

O Windows não oferece suporte a datas anteriores a 1601. Consulte a estrutura FILETIME para obter detalhes.

O controle é baseado no calendário gregoriano, que foi introduzido em 1753. Ele não calculará datas que sejam consistentes com o calendário juliano.

Interface do usuário do seletor de data e hora

A área do cliente de um controle DTP (seletor de data e hora) exibe informações de data ou hora, ou ambas, e atua como a interface por meio da qual os usuários modificam as informações. A data pode ser selecionada de um calendário ou usando um controle ascendente; a hora pode ser alterada digitando em campos que são definidos pelas cadeias de caracteres de formato do controle. Opcionalmente, o controle exibe uma caixa de seleção. Quando ele é verificado, o valor no controle pode ser recuperado; caso contrário, o controle é considerado não inicializado.

A ilustração a seguir mostra uma janela que contém três controles de seletor de data. O primeiro controle de seleção de data foi criado com o estilo DTS_SHOWNONE, o segundo com o estilo DTS_UPDOWN e o terceiro sem estilos especiais. No terceiro controle, o usuário clicou na seta para baixo para exibir o calendário.

screen shot of a window that demonstrates three styles of date-picker controls

A ilustração a seguir mostra uma janela com três controles que contêm a hora.

O primeiro controle foi criado com o estilo DTS_TIMEFORMAT e mostra a hora na hora padrão, que consiste em quatro campos. O usuário pode digitar um valor válido em qualquer um desses campos ou selecionar o campo e alterar o valor usando o controle para cima ou as teclas de seta.

O segundo controle mostra um formato personalizado definido usando DateTime_SetFormat. Assim como no primeiro controle, o usuário pode alterar os campos de hora digitando ou usando as teclas de seta. O dia da semana pode ser alterado selecionando uma data no calendário que é aberta quando o usuário clica na seta para baixo.

O terceiro controle mostra como o texto arbitrário pode ser adicionado ao controle. O usuário pode selecionar uma hora (de 1 a 24) digitando, usando as teclas de seta ou usando o controle up-down.

screen shot of a window that shows three controls that contain the time

O controle DTP atualiza automaticamente as informações internas com base na entrada do usuário. O controle reconhece o seguinte como entrada válida.

Categoria de entrada Descrição
Teclas de direção O controle aceita teclas de seta para navegar pelos campos no controle e alterar valores. O usuário pode pressionar as teclas ou para se mover pelo controle Se o usuário tentar passar do último campo em uma determinada direção, o foco do teclado "enrola" para o campo no lado oposto do controle. As chaves e alteram os valores no campo atual incrementalmente.
Fim e Início O controle aceita as chaves virtuais VK_END e VK_HOME para alterar o valor dentro do campo atual para seus limites superior e inferior, respectivamente.
Teclas de Função A tecla ativa o modo de edição. A tecla faz com que o controle exiba um controle de calendário de mês suspenso (pressionar também faz isso).
Números O controle aceita entrada numérica em segmentos de dois caracteres. Se o valor inserido pelo usuário for inválido (como definir o mês como 14), o controle o rejeitará e redefinirá a exibição para o valor anterior.
Mais e menos O controle aceita as teclas virtuais VK_ADD e VK_SUBTRACT do teclado numérico para incrementar e diminuir o valor no campo atual.

 

Os controles DTP que não usam o estilo DTS_UPDOWN exibem um botão de seta. Se o usuário clicar nesse botão, um controle de calendário do mês será suspenso. O usuário pode selecionar uma data específica clicando em uma área do calendário.

Estilos e formatos de controle do seletor de data e hora

Os controles DTP (seletor de data e hora) têm vários estilos de controle do seletor de data e hora que determinam a aparência e o comportamento de um controle. Especifique o estilo ao criar o controle com o parâmetro dwStyle de CreateWindowEx. Para recuperar ou alterar o estilo da janela depois de criar o controle, use GetWindowLong e SetWindowLong.

Formatos predefinidos

Há três formatos predefinidos disponíveis para exibir a data e um para exibir a hora. Defina esses formatos escolhendo um dos seguintes estilos de janela.

Formatar Descrição
DTS_LONGDATEFORMAT A exibição ficará assim: "Sexta-feira, 19 de abril de 1996".
DTS_SHORTDATEFORMAT A tela ficará assim: "19/04/96".
DTS_SHORTDATECENTURYFORMAT Versão 5.80. A tela ficará assim: "19/04/1996".
DTS_TIMEFORMAT A tela ficará assim: "17:31:42".

 

Formatos personalizados

Um controle DTP depende de uma cadeia de caracteres de formato para determinar como ele exibirá campos de informações. Se os formatos predefinidos não forem suficientes, você poderá criar um formato personalizado definindo sua própria cadeia de caracteres de formato. Os formatos personalizados fornecem maior flexibilidade para um aplicativo. Eles permitem que você especifique a ordem em que o controle exibirá campos de informações. Você pode incluir corpo de texto, bem como campos de retorno de chamada para solicitar informações do usuário. Depois que a cadeia de caracteres é criada, você a atribui ao controle DTP com uma mensagem DTM_SETFORMAT.

Cadeias de caracteres de formato

Uma cadeia de caracteres de formato DTP consiste em uma série de elementos que representam uma determinada informação e definem seu formato de exibição. Os elementos serão exibidos na ordem em que aparecem na cadeia de caracteres de formato.

Os elementos de formato de data e hora serão substituídos pela data e hora reais. Eles são definidos pelos seguintes grupos de caracteres.

Element Descrição
"d" O dia de um ou dois dígitos.
"dd" O dia de dois dígitos. Os valores de um dígito do dia são precedidos por um zero.
"ddd" A abreviação de três caracteres do dia da semana.
"dddd" O nome completo do dia da semana.
"h" A hora de um ou dois dígitos no formato de 12 horas.
"hh" A hora de dois dígitos no formato de 12 horas. Os valores de um dígito são precedidos por um zero.
"H" A hora de um ou dois dígitos no formato de 24 horas.
"HH" A hora de dois dígitos no formato de 24 horas. Os valores de um dígito são precedidos por um zero.
"m" O minuto de um ou dois dígitos.
"mm" O minuto de dois dígitos. Os valores de um dígito são precedidos por um zero.
“M” O número do mês de um ou dois dígitos.
"MM" O número do mês de dois dígitos. Os valores de um dígito são precedidos por um zero.
"MMM" A abreviação de três caracteres do mês.
"MMMM" O nome completo do mês.
"t" A abreviatura AM/PM de uma letra (ou seja, AM é exibida como "A").
"tt" A abreviatura AM/PM de duas letras (ou seja, AM é exibida como "AM").
"yy" Os dois últimos dígitos do ano (ou seja, 1996 seriam exibidos como "96").
"yyyy" O ano inteiro (ou seja, 1996 seria exibido como "1996").

 

Para tornar as informações mais legíveis, você pode adicionar corpo de texto à cadeia de caracteres de formato colocando-a entre aspas simples. Espaços e sinais de pontuação não precisam ser citados.

Observação

Caracteres não formatados que não são delimitados por aspas simples resultarão em exibição imprevisível pelo controle DTP.

Por exemplo, para exibir a data atual com o formato "'Hoje é: 04:22:31 terça-feira, 23 de março de 1996", a cadeia de caracteres de formato é "'Hoje é: 'hh':'m':'s dddd MMM dd', 'yyyy". Para incluir uma única citação no corpo do texto, use duas aspas simples consecutivas. Por exemplo, "'Don't forget' MMM dd', yyyy" produz uma saída que se parece com: Não se esqueça de 23 de março de 1996. Não é necessário usar aspas com a vírgula, então "'Don't forget' MMM dd, yyyy" também é válido, e produz a mesma saída.

Campos de retorno de chamada

Além das cadeias de caracteres de formato padrão e do corpo do texto, você também pode definir certas partes da exibição como campos de retorno de chamada. Esses campos podem ser usados para consultar o usuário em busca de informações. Para declarar um campo de retorno de chamada, inclua um ou mais caracteres "X" (código ASCII 88) em qualquer lugar na cadeia de caracteres de formato. Você pode criar campos de retorno de chamada que tenham uma identidade exclusiva repetindo o caractere "X". Assim, a string de formato "XX dddd MMM dd', 'yyy XXX" contém dois campos de retorno de chamada exclusivos, "XX" e "XXX". Como outros campos de controle DTP, os campos de retorno de chamada são exibidos na ordem da esquerda para a direita com base em sua localização na cadeia de caracteres de formato.

Quando o controle DTP analisa a cadeia de caracteres de formato e encontra um campo de retorno de chamada, ele envia códigos de notificação DTN_FORMAT e DTN_FORMATQUERY . O elemento de cadeia de caracteres de formato correspondente ao campo de retorno de chamada é incluído com as notificações para permitir que o aplicativo de recebimento determine qual campo de retorno de chamada está sendo consultado. O proprietário do controle deve responder a essas notificações para garantir que as informações personalizadas sejam exibidas corretamente.

Mensagens de notificação do controle do seletor de data e hora

Um controle de seletor de data e hora (DTP) envia códigos de notificação quando recebe entrada ou processos do usuário e reage a campos de retorno de chamada. O pai do controle recebe esses códigos de notificação na forma de mensagens WM_NOTIFY.

Os códigos de notificação a seguir são usados com controles DTP.

Código de notificação Descrição
DTN_CLOSEUP Indica que o calendário de mês suspenso está prestes a ser removido.
DTN_DATETIMECHANGE Sinaliza uma mudança dentro do controle DTP.
DTN_DROPDOWN Indica que o calendário do mês suspenso está prestes a ser exibido.
DTN_FORMAT Solicita que o texto seja exibido em uma parte da cadeia de caracteres de formato descrita como um campo de retorno de chamada.
DTN_FORMATQUERY Solicita informações sobre o tamanho máximo permitido do texto a ser exibido em um campo de retorno de chamada.
DTN_USERSTRING Sinaliza o fim da operação de edição de um usuário dentro do controle. Essa notificação é enviada somente por controles DTP que usam o estilo DTS_APPCANPARSE.
DTN_WMKEYDOWN Sinaliza que o usuário pressionou uma tecla em um campo de retorno de chamada do controle DTP.

 

Referência de controle do seletor de data e hora