Date and Time Picker Controls

A date and time picker (DTP) control provides a simple and intuitive interface through which to exchange date and time information with a user. For example, with a DTP control you can ask the user to enter a date and then retrieve his or her selection with ease.

About Date and Time Picker Controls

Date and time picker controls are implemented in version 4.70 and later of Comctl32.dll. To create a DTP control call CreateWindowEx and specify DATETIMEPICK_CLASS as the window class. The class is registered when the date and time picker class is loaded from the common control dynamic-link library (DLL). Register this class by calling the InitCommonControlsEx function, while specifying the ICC_DATE_CLASSES bit flag in the accompanying INITCOMMONCONTROLSEX structure.

Note

Windows does not support dates prior to 1601. See the FILETIME structure for details.
The DTP control is based on the Gregorian calendar, which was introduced in 1753. It will not calculate dates that are consistent with the Julian calendar that was in use prior to 1753.

Date and Time Picker User Interface

The client area of a date and time picker (DTP) control displays date and time information and acts as the interface through which users modify the information. The control's display consists of fields that are defined by the control's Format Strings. Additionally, the control will display a check box when the DTS_SHOWNONE style is in use.

Each field in the control displays a portion of the date and time information that the control stores internally. The user can click a field to set keyboard focus and then provide keyboard input to change the information represented by that field. The DTP control automatically updates internal information based on the user's input. The control recognizes the following as valid input.

Input Category	Description
Arrow Keys	The control accepts arrow keys to navigate the fields in the control and change values. The user can press the or keys to move through the control. If the user attempts to move past the last field in a given direction, the keyboard focus "wraps around" to the field on the opposite side of the control. The and keys change values in the current field incrementally.
End and Home	The control accepts the VK_END and VK_HOME virtual keys to change the value within the current field to its upper and lower limits, respectively.
Function Keys	The key activates edit mode. The key causes the control to display a drop-down month calendar control (pressing does this as well).
Numbers	The control accepts numeric input in two-character segments. If the value entered by the user is invalid (like setting the month to 14), the control rejects it and resets the display to the previous value.
Plus and Minus	The control accepts the VK_ADD and VK_SUBTRACT virtual keys from the numeric keypad to increment and decrement the value in the current field.

DTP controls that do not use the DTS_UPDOWN style display an arrow button. If the user clicks this button, a month calendar control drops down. The user can select a specific date by clicking an area of the calendar.

Date and Time Picker Control Styles and Formats

Date and time picker (DTP) controls have several Date and Time Picker Control Styles that determine a control's appearance and behavior. Specify the style when creating the control with the dwStyle parameter of CreateWindowEx. To retrieve or change the window style after you have created the control, use GetWindowLong and SetWindowLong .

Preset Formats

There are three preset formats available for displaying the date and one for displaying time. Set these formats by choosing one of the following window styles:

DTS_LONGDATEFORMAT	The display will look like: "Friday, April 19, 1996".
DTS_SHORTDATEFORMAT	The display will look like: "4/19/96".
DTS_SHORTDATECENTURYFORMAT	Version 5.80. The display will look like: "4/19/1996".
DTS_TIMEFORMAT	The display will look like: "5:31:42 PM".

Custom formats

A DTP control relies on a format string to determine how it will display fields of information. If the preset formats are not sufficient, you can create a custom format by defining your own format string. Custom formats provide greater flexibility for an application. They enable you to specify the order in which the control will display fields of information. You can include body text as well as callback fields for requesting information from the user. Once the string is created, you assign it to the DTP control with a DTM_SETFORMAT message.

Format Strings

A DTP format string consists of a series of elements that represent a particular piece of information and define its display format. The elements will be displayed in the order they appear in the format string.

Date and time format elements will be replaced by the actual date and time. They are defined by the following groups of characters:

Element	Description
"d"	The one- or two-digit day.
"dd"	The two-digit day. Single-digit day values are preceded by a zero.
"ddd"	The three-character weekday abbreviation.
"dddd"	The full weekday name.
"h"	The one- or two-digit hour in 12-hour format.
"hh"	The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
"H"	The one- or two-digit hour in 24-hour format.
"HH"	The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
"m"	The one- or two-digit minute.
"mm"	The two-digit minute. Single-digit values are preceded by a zero.
"M"	The one- or two-digit month number.
"MM"	The two-digit month number. Single-digit values are preceded by a zero.
"MMM"	The three-character month abbreviation.
"MMMM"	The full month name.
"t"	The one-letter AM/PM abbreviation (that is, AM is displayed as "A").
"tt"	The two-letter AM/PM abbreviation (that is, AM is displayed as "AM").
"yy"	The last two digits of the year (that is, 1996 would be displayed as "96").
"yyyy"	The full year (that is, 1996 would be displayed as "1996").

To make the information more readable, you can add body text to the format string by enclosing it in single quotes. Spaces and punctuation marks do not need to be quoted.

Note Nonformat characters that are not delimited by single quotes will result in unpredictable display by the DTP control.

For example, to display the current date with the format "'Today is: 04:22:31 Tuesday Mar 23, 1996", the format string is "'Today is: 'hh':'m':'s dddd MMM dd', 'yyyy". To include a single quote in your body text, use two consecutive single quotes. For example, "'Don''t forget' MMM dd',' yyyy" produces output that looks like: Don't forget Mar 23, 1996. It is not necessary to use quotes with the comma, so "'Don''t forget' MMM dd, yyyy" is also valid, and produces the same output.

Callback fields

In addition to the standard Format Strings and body text, you can also define certain parts of the display as Callback fields. These fields can be used to query the user for information. To declare a callback field, include one or more "X" characters (ASCII Code 88) anywhere in the format string. You can create callback fields that have a unique identity by repeating the "X" character. Thus, the format string "XX dddd MMM dd', 'yyy XXX" contains two unique callback fields, "XX" and "XXX". Like other DTP control fields, callback fields are displayed in left-to-right order based on their location in the format string.

When the DTP control parses the format string and encounters a callback field, it sends DTN_FORMAT and DTN_FORMATQUERY notification messages. The format string element corresponding to the callback field is included with the notifications to allow the receiving application to determine which callback field is being queried. The owner of the control must respond to these notifications to ensure that the custom information is properly displayed.

Date and Time Picker Control Notification Messages

A date and time picker (DTP) control sends notification messages when it receives user input or processes and reacts to callback fields. The parent of the control receives these notification messages in the form of WM_NOTIFY messages.

The following notification messages are used with DTP controls.

Notification	Description
DTN_CLOSEUP	Indicates that the drop-down month calendar is about to be removed.
DTN_DATETIMECHANGE	Signals a change within the DTP control.
DTN_DROPDOWN	Indicates that the drop-down month calendar is about to be displayed.
DTN_FORMAT	Requests text to display in a portion of the format string described as a callback field.
DTN_FORMATQUERY	Requests information about the maximum allowable size of the text to be displayed in a callback field.
DTN_USERSTRING	Signals the end of a user's edit operation within the control. This notification is sent only by DTP controls that use the DTS_APPCANPARSE style.
DTN_WMKEYDOWN	Signals that the user has pressed a key in a callback field of the DTP control.

Creating a Date and Time Picker Control

To create a date and time picker (DTP) control, use the CreateWindowEx function, specifying DATETIMEPICK_CLASS as the window class. You must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_DATE_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.

The following example creates a DTP control in an existing modeless dialog box. It uses the DTS_SHOWNONE style to enable the user to simulate deactivation of the date within the control.

		
//  CreateDatePick creates a DTP control within a dialog box.
//  Returns the handle to the new DTP control if successful, or NULL 
//  otherwise.
//
//    hwndMain - The handle to the main window.
//    g_hinst  - global handle to the program instance.

HWND WINAPI CreateDatePick(hwndMain)
{
    HWND hwndDP = NULL;
    HWND hwndDlg = NULL;
    INITCOMMONCONTROLSEX icex;

    icex.dwSize = sizeof(icex);
    icex.dwICC = ICC_DATE_CLASSES;

    InitCommonControlsEx(&icex);

    hwndDlg = CreateDialog  (g_hinst,
                             MAKEINTRESOURCE(IDD_DIALOG1),
                             hwndMain,
                             DlgProc);

    if(hwnDlg)
        hwndDP = CreateWindowEx(0,
                             DATETIMEPICK_CLASS,
                             "DateTime",
                             WS_BORDER|WS_CHILD|WS_VISIBLE|DTS_SHOWNONE,
                             20,50,220,20,
                             hwndDlg,
                             NULL,
                             g_hinst,
                             NULL);

    return (hwndDP);
}

Processing Date and Time Picker Notifications

The following example processes the DTN_DATETIMECHANGE, DTN_FORMAT, DTN_FORMATQUERY, and DTN_WMKEYDOWN notifications by calling the DoDateTimeChange, DoFormatQuery, DoFormat, and DoWMKeydown application-defined functions.

Other topics in this chapter provide additional information on these notifications. See Supporting Callback Fields and Processing the DTN_DATETIMECHANGE Notification Message for additional information.

		
BOOL WINAPI DoNotify(HWND hwnd, WPARAM wParam, LPARAM lParam)
{
    LPNMHDR hdr = (LPNMHDR)lParam;

    switch(hdr->code){

        case DTN_DATETIMECHANGE:{
            LPNMDATETIMECHANGE lpChange = (LPNMDATETIMECHANGE)lParam;
            DoDateTimeChange(lpChange);
        }
	    break;

        case DTN_FORMATQUERY:{
            LPNMDATETIMEFORMATQUERY lpDTFQuery = (LPNMDATETIMEFORMATQUERY)lParam;

            // Process DTN_FORMATQUERY to ensure that the control
            // displays callback information properly.
            DoFormatQuery(hdr->hwndFrom, lpDTFQuery);
        }
        break;

        case DTN_FORMAT:{
            LPNMDATETIMEFORMAT lpNMFormat = (LPNMDATETIMEFORMAT) lParam;

            // Process DTN_FORMAT to supply information about callback
            // fields (fields) in the DTP control.
            DoFormat(hdr->hwndFrom, lpNMFormat);
        }
        break;

        case DTN_WMKEYDOWN:{
            LPNMDATETIMEWMKEYDOWN lpDTKeystroke = 
                            (LPNMDATETIMEWMKEYDOWN)lParam;

            // Process DTN_WMKEYDOWN to respond to a user's keystroke in
            // a callback field.
            DoWMKeydown(hdr->hwndFrom, lpDTKeystroke);
        }
        break;
    }

    // All of the above notifications require the owner to return zero.
    return FALSE;
}

Processing the DTN_DATETIMECHANGE Notification

A date and time picker (DTP) control sends the DTN_DATETIMECHANGE message whenever a change occurs. This message will be generated if the user changes one of the fields in the control or changes the state of the control's check box (DTS_SHOWNONE only).

The following example is an application-defined function designed to update a static control within a dialog box. The text within the static control is changed to reflect the current state of the DTP control.

		
void WINAPI DoDateTimeChange(LPNMDATETIMECHANGE lpChange)
{
    // If the user has unchecked the DTP's check box, change the
    // text in a static control to show the appropriate message.
    //
    // g_hwndDlg - a program-global address of a dialog box.

    if(lpChange->dwFlags == GDT_NONE)
        SetDlgItemText(g_hwndDlg, IDC_STATUS, "Disabled");
    else
        SetDlgItemText(g_hwndDlg, IDC_STATUS, "Active");
}

Supporting Callback Fields in a DTP control

If you plan to use callback fields with the date and time picker (DTP) controls in your application, you must be prepared to handle DTN_FORMATQUERY, DTN_FORMAT, and DTN_WMKEYDOWN notification messages. For additional information about callback fields, see Callback fields.

This section contains information about how your application can process these notification messages. There are several examples of source code for application-defined functions. The following list shows notification messages with sample functions that process them.

Notification Message	Sample Function
DTN_FORMATQUERY	DoFormatQuery
DTN_FORMAT	DoFormat
DTN_WMKEYDOWN	DoWMKeydown

The DoFormatQuery application-defined function

A date and time picker (DTP) control sends a DTN_FORMATQUERY notification message to request information about the maximum possible size of a callback field within the control. Handling this message ensures that all fields are displayed properly. The following DoFormatQuery application-defined function processes the DTN_FORMATQUERY notification message by calculating the width of the widest possible string for a given callback field.

		
//  DoFormatQuery processes DTN_FORMATQUERY messages to ensure that the
//  DTP control displays callback fields properly.
//

void WINAPI DoFormatQuery(
 HWND hwndDP, 
 LPNMDATETIMEFORMATQUERY lpDTFQuery)
{
    HDC hdc;
    HFONT hFont, hOrigFont;

    //  Prepare the device context for GetTextExtentPoint32 call.
    hdc = GetDC(hwndDP);

    hFont = FORWARD_WM_GETFONT(hwndDP, SendMessage);

    if(!hFont)
        hFont = (HFONT)GetStockObject(DEFAULT_GUI_FONT);

    hOrigFont = SelectObject(hdc, hFont);

    // Check to see if this is the callback segment desired. If so,
    // use the longest text segment to determine the maximum 
    // width of the callback field, and then place the information into 
    // the NMDATETIMEFORMATQUERY structure.
    if(!lstrcmp("XX",lpDTFQuery->pszFormat))
	    GetTextExtentPoint32 (hdc,
                          "366",  // widest date string
                          3,
	                      &lpDTFQuery->szMax);

    // Reset the font in the device context; then release the context.
    SelectObject(hdc,hOrigFont);
    ReleaseDC(hwndDP, hdc);
}

The DoFormat application-defined function

A date and time picker (DTP) control sends the DTN_FORMAT notification to request text that will be displayed in a callback field of the control. By handling this notification message, you allow the DTP control to display information that it does not natively support.

The following DoFormat application-defined function processes DTN_FORMAT notification messages by providing a text string for a callback field. DoFormat calls the GetDayNum application-defined function to request the day number to be used in the callback string.

		
//  DoFormat processes DTN_FORMAT to provide the text for a callback
//  field in a DTP control. In this example, the callback field
//  contains a value for the day of year. The function calls the 
//  application-defined function GetDayNum (below) to retrieve
//  the correct value. StringCchPrintf truncates the formatted string if
//  the entire string will not fit into the destination buffer. 

void WINAPI DoFormat(HWND hwndDP, LPNMDATETIMEFORMAT lpDTFormat)
{
HRESULT hr = StringCchPrintf(lpDTFormat->szDisplay,
                sizeof(lpDTFormat->szDisplay)/sizeof(lpDTFormat->szDisplay[0]),
                "%d",GetDayNum(&lpDTFormat->st));
if(SUCCEEDED(hr))
{
// TODO: Write code to handle the case when the function succeeds.      
}
else
{
// TODO: Write code to handle the case when the function fails or the string 
// is truncated.
}

The GetDayNum application-defined function

The application-defined sample function DoFormat calls the following GetDayNum application-defined function to request the day number based on the current date. GetDayNum returns an INT value that represents the current day of the year, from 0 to 366. This function calls another application-defined function, IsLeapYr, during processing.

		
//  GetDayNum is an application-defined function that retrieves the 
//  correct day of year value based on the contents of a given 
//  SYSTEMTIME structure. This function calls the IsLeapYr function to 
//  check if the current year is a leap year. The function returns an 
//  integer value that represents the day of year.

int WINAPI GetDayNum(SYSTEMTIME *st)
{
    int iNormYearAccum[ ] = {31,59,90,120,151,181,
                            212,243,273,304,334,365};
    int iLeapYearAccum[ ] = {31,60,91,121,152,182,
                            213,244,274,305,335,366};
    int iDayNum;

    if(IsLeapYr(st->wYear))
        iDayNum=iLeapYearAccum[st->wMonth-2]+st->wDay;
    else
        iDayNum=iNormYearAccum[st->wMonth-2]+st->wDay;

    return (iDayNum);
}

The IsLeapYr application-defined function

The application-defined sample function GetDayNum calls the IsLeapYr function to determine whether the current year is a leap year. IsLeapYr returns a BOOL value that is TRUE if it is a leap year and FALSE otherwise.

//  IsLeapYr determines if a given year value is a leap year. The
//  function returns TRUE if the current year is a leap year, and 
//  FALSE otherwise.

BOOL WINAPI IsLeapYr(int iYear)
{
    int iQuotient;
    BOOL fLeapYr = FALSE;

    // If the year is evenly divisible by 4 and not by 100, then this 
    // is a leap year.
    if(!(iYear%4) && (iYear%100)) 
        fLeapYr = TRUE;
    else{
        // If the year is evenly divisible by 4 and 100, then check to
        // see if the quotient of year divided by 100 is also evenly 
        // divisible by 4. If it is, then this is a leap year.
        if(!(iYear%4) && !(iYear%100)){
            iQuotient = iYear/100;
            if(!(iQuotient%4)) fLeapYr = TRUE;
        }
    }

    return (fLeapYr);
}

The DoWMKeydown application-defined function

Date and time picker (DTP) controls send the DTN_WMKEYDOWN message to report that the user has typed input in a callback field. Handling this message allows you to emulate the same keyboard responses supported for standard DTP fields or provide custom responses. The following DoWMKeydown application-defined function provides an example of how DTN_WMKEYDOWN notifications can be handled.

		
//  DoWMKeydown increments or decrements the day of month according 
//  to user keyboard input.

void WINAPI DoWMKeydown(
 HWND hwndDP,
 LPNMDATETIMEWMKEYDOWN lpDTKeystroke)
{
    int delta =1;
    if(!lstrcmp(lpDTKeystroke->pszFormat,"XX")){
        switch(lpDTKeystroke->nVirtKey){
            case VK_DOWN:
            case VK_SUBTRACT:
                delta = -1;  // fall through

            case VK_UP:
            case VK_ADD:
                lpDTKeystroke->st.wDay += delta;
                break;
        }
    }
}