This message sets the display of a date and time picker (DTP) control based on a specified format string.
At a Glance
| Header file: | Commctrl.h |
| Windows CE versions: | 2.0 and later |
| Related macro: | DateTime_SetFormat |
Syntax
DTM_SETFORMAT wParam = 0; lParam = (LPARAM) lpszFormat;
Parameters
lpszFormat
Long pointer to a null-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style. The format string is a combination of string fragments. It is interpreted literally, with the exception of the following string fragments:
| Value | 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.” |
| “X” | A callback field. The control still uses the other valid format characters, and queries the owner to fill in the “X” portion. Therefore, the owner must be prepared to handle the DTN_WMKEYDOWN, DTN_FORMAT, and DTN_FORMATQUERY notification messages. Multiple “X” characters can be used in 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; that is, 1996 would be displayed as “96.” |
| "yyyy" | The full year; that is, 1996 would be displayed as “1996.” |
Return Values
Nonzero indicates success. Zero indicates otherwise.
Remarks
It is acceptable to include extra characters within the format string to produce a richer display. However, any nonformat characters must be enclosed within single quotes. For example, the format string “’Today is: ‘hh’:’m’:’s ddddMMMdd’, ‘yyy” would produce output like “Today is: 04:22:31 Tuesday Mar 23, 1996”.
No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L”yyyy” and L”yy” (the ‘L’ indicates a Unicode (16-bit characters) string). If L”y” is passed in, the function assumes L”yy”. If L”yyy” is passed in, the function assumes L”yyyy”. If more than 4 date (L”dddd”) or 4 month (L”MMMM”) pictures are passed in, then the function defaults to L”dddd” or L”MMMM”.
Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as “May ‘93”, the format string would be: L”MMMM ‘’’’yy” The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.
Note
A DTP control tracks locale changes when it is using the default format string. If you set a custom format string, it will not be updated in response to locale changes.