Displaying Information

As stated earlier, a date and time picker control relies on a format string to determine how it will display information. By default, a date and time picker control can display time information in three preset formats or according to a custom format string. In a custom format string, you can specify the order in which the control will display information or indicate specific callback fields. The format characters of the format string define the display and field layout for the date and time picker control.

The following list shows Window styles used by the preset formats, which are format strings.

DTS_LONGDATEFORMAT
The control displays the date in long format. The default format string for this style is defined by LOCALE_SLONGDATEFORMAT, which produces the output "Friday, April 19, 1998."
DTS_SHORTDATEFORMAT
The control displays the date in short format, which is the default style setting. The default format string for this style is defined by LOCALE_SSHORTDATE, which produces the output "4/19/98."
DTS_TIMEFORMAT
The control displays the time. The default format string for this style is defined by LOCALE_STIMEFORMAT, which produces the output "5:31:42 PM." An up-down control is placed to the right of the date and time picker control to modify time values.

You can customize the display of a date and time picker control using custom format strings. Date and time picker controls support specified format characters that you can combine to create a format string. To assign the format string to the date and time picker control, use the DTM_SETFORMAT message.

The following table shows format characters supported by date and time picker controls.

String fragment
Description
d The one-digit 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
gg The period and era string contained in the CAL_SERASTRING value associated with the specified locale. Windows CE ignores this element if the date to be formatted does not have an associated era or period string.
h The one-digit 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-digit 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-digit or two-digit minute
mm The two-digit minute. Single-digit values are preceded by a zero.
M The one-digit 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 A.M. and P.M. abbreviation (that is, "AM" is displayed as "A")
tt The two-letter A.M. and P.M. abbreviation (that is, "AM" is displayed as "AM")
X The callback field. The control uses the other valid format characters and queries the application to fill in the "X" portion of the string. The application must be prepared to handle the DTN_WMKEYDOWN, DTN_FORMAT, and DTN_FORMATQUERY notification messages. Multiple "X" characters can be used in a series to signify unique callback fields.
y The year is displayed as the last two digits, but with no leading zero for years less than 10.
yy The last two digits of the year. For example, 1998 would be displayed as "98."
yyy The full year. For example, 1998 would be displayed as "1998."

You can add body text to the format string. For example, if you want the control to display the current date with the format "Today is: 04:22:31 Tuesday Mar 23, 1998," use the following format string: Today is: 'hh'':m': 's ddddMMMdd', 'yyy'. The window procedure for a command bar automatically sets the size of the command bar and positions it along the top of the parent window client area. It also destroys the command bar when its parent window is destroyed. Body text must be enclosed in single quotation marks.

Note that segments of nonformat characters in the preceding example are delimited by single quotation marks. Failure to surround body text in this way will result in unpredictable display by the date and time picker control.