wpf-6947-controls-and-libraries-data-editors-common-features-masked-input-mask-type-date-time.md
This document describes the DateTime mask modes, which are specifically designed for entering date/time values in different formats. Specific DateTime masks are dependent upon the current culture’s settings.
For information on the other masked modes, see the mask types document.
The DevExpress WPF Data Editors support the following DateTime mask modes:
To enable a particular DateTime mask mode, set the TextEdit.MaskType (or the TextEditSettings.MaskType for in-place editors) property to MaskType.DateTime or MaskType.DateTimeAdvancingCaret. The mask itself should be specified via the TextEdit.Mask (or TextEditSettings.Mask for in-place editors) property.
The DateEdit control uses the MaskType.DateTime mask mode by default. To enable automatic caret advancement, set the editor’s mask type to MaskType.DateTimeAdvancingCaret.
You can use either predefined or custom masks. These masks are similar to the display formats described in the Date and Time Format Strings document. Set the TextEdit.MaskUseAsDisplayFormat (TextEditSettings.MaskUseAsDisplayFormat for in-place editors) to format editor values using mask when the editor is not in edit mode.
Most of the masks listed below depend on the current culture. For example, the culture defines the names of months, the symbol to use as the date separator, the short and long date patterns, etc. All these settings are provided by the DateTimeFormat property of the current culture. To customize these settings for your system use the Regional Options dialog in the control panel.
The date/time masks support the following calendars: Gregorian, Korean, Taiwan, and Thai Buddhist.
Predefined masks allow end users to edit date/time values according to common patterns. A standard mask consists of a single character which identifies the appropriate pattern. The table below lists the available masks.
|
Standard mask
|
Name
|
Description
|
Samples
Culture: English (U.S.)
| | --- | --- | --- | --- | |
d
|
Short date pattern
|
The mask matches the pattern specified by the ShortDatePattern property.
|
| |
D
|
Long date pattern
|
The mask matches the pattern specified by the LongDatePattern property.
|
| |
t
|
Short time pattern
|
The mask matches the pattern specified by the ShortTimePattern property.
|
| |
T
|
Long time pattern
|
The mask matches the pattern specified by the LongTimePattern property.
|
| |
f
|
Full date/time pattern (short time)
|
The mask combines the long date and short time patterns, separated by the space character.
|
| |
F
|
Full date/time pattern (long time)
|
The mask matches the pattern specified by the FullDateTimePattern property.
|
| |
g
|
General date/time pattern (short time)
|
The mask combines the short date and short time patterns, separated by the space character.
|
| |
G
|
General date/time pattern (long time)
|
The mask combines the short date and long time patterns, separated by the space character.
|
| |
M or m
|
Month day pattern
|
The mask matches the pattern specified by the MonthDayPattern property.
|
| |
R or r
|
RFC1123 pattern
|
The mask matches the pattern specified by the RFC1123Pattern property.
|
| |
s
|
Sortable date/time pattern that conforms to ISO 8601
|
The mask matches the pattern specified by the SortableDateTimePattern property.
|
| |
u
|
Universal sortable date/time pattern
|
The mask matches the pattern specified by the UniversalSortableDateTimePattern property.
|
| |
Y or y
|
Year month pattern
|
The mask matches the pattern specified by the YearMonthPattern property.
|
|
You can use custom masks if the predefined ones do not suit your particular needs. Use the following mask specifiers to create custom masks for editing date/time values.
|
Mask specifier
|
Description
| | --- | --- | |
d
|
A placeholder for the day of the month. If the day is a single digit only (1-9), then it’s displayed as a single digit.
If the d specifier is used alone, without other custom specifiers, it’s interpreted as the standard mask (short date pattern). If the d specifier is passed with other custom specifiers or the % character, it is interpreted as a custom mask specifier.
| |
dd
|
A placeholder for the day of the month. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09).
| |
ddd
|
Displays the abbreviated name of the current day. The abbreviated names are determined by the DateTimeFormatInfo.AbbreviatedDayNames property of the current culture.
The value represented by this specifier cannot be edited.
| |
dddd (plus any number of additional “d” characters)
|
Displays the full name of the current day. The full names of the days are determined by the DateTimeFormatInfo.DayNames property of the current culture.
The value represented by this specifier cannot be edited.
| |
f or F
|
A placeholder for seconds fractions represented in one digit.
If the f/F specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (full date/time pattern). If the f/F specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
| |
ff or FF
|
A placeholder for seconds fractions represented in two digits.
| |
fff or FFF
|
A placeholder for seconds fractions represented in three digits.
| |
ffff or FFFF
|
Displays seconds fractions represented in four digits.
The value represented by this specifier cannot be edited.
| |
fffff or FFFFF
|
Displays seconds fractions represented in five digits.
The value represented by this specifier cannot be edited.
| |
ffffff or FFFFFF
|
Displays seconds fractions represented in six digits.
The value represented by this specifier cannot be edited.
| |
fffffff or FFFFFFF
|
Displays seconds fractions represented in seven digits.
The value represented by this specifier cannot be edited.
| |
g
|
Displays the era (“A.D.”, for example) for the current date/time value.
The value represented by this specifier cannot be edited.
| |
h
|
A placeholder for the hour part of the date/time value (range 1-12).
| |
hh
|
A placeholder for the hour part of the date/time value (range 1-12). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
| |
H
|
A placeholder for the hour part of the date/time value (range 0-23).
| |
HH
|
A placeholder for the hour part of the date/time value (range 0-23). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
| |
m
|
A placeholder for the minutes of the date/time value (range 0-59).
| |
mm
|
A placeholder for the minutes of the date/time value (range 0-59). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
| |
M
|
A placeholder for the month in this position, measured as a number (range 1-12).
| |
MM
|
A placeholder for the month in this position, measured as a number (range 1-12). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
| |
MMM
|
A placeholder for the abbreviated name of the month. The abbreviated names of the months are determined by the DateTimeFormatInfo.AbbreviatedMonthNames property of the current culture.
| |
MMMM
|
A placeholder for the full name of the month. The full names of the months are determined by the DateTimeFormatInfo.MonthNames property of the current culture.
| |
s
|
A placeholder for the seconds part of the date/time value (range 0-59).
If the s specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (sortable date/time pattern). If the s specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
| |
ss
|
A placeholder for the seconds part of the date/time value (range 0-59). This pattern inserts two placeholders to enter a value. If a single digit is entered it’s preceded with a 0.
| |
t
|
A placeholder for the first character of the A.M./P.M. designator of the date/time value.
If the t specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (short time pattern). If the t specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
| |
tt
|
A placeholder for the A.M./P.M. designator of the date/time value.
| |
y
|
A placeholder for entering the last two digits of the year of the date/time value.
If the y specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (year month pattern). If the y specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
| |
yy
|
A placeholder for entering the last two digits of the year of the date/time value. This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
| |
yyyy
|
A placeholder for entering the year part of the date/time value including the century.
| |
z
|
Displays the time zone offset for the system’s current time zone in whole hours. The offset is always displayed with a leading sign (zero is displayed as +0), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich mean time (-) the current time zone is. The range of values is –12 to +13. If the offset is a single digit (0–9), it’s displayed as a single digit with an appropriate leading sign.
The value represented by this specifier cannot be edited.
| |
zz
|
Displays the time zone offset for the system’s current time zone in whole hours. The offset is always displayed with a leading or trailing sign (zero is displayed as +00), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich Mean Time (-) the current time zone is. The range of values is –12 to +13. If the offset is a single digit (0–9), it’s formatted with a preceding 0 (01–09) with an appropriate leading sign.
The value represented by this specifier cannot be edited.
| |
zzz
|
Displays the time zone offset for the system’s current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as +00:00), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich Mean Time (-) the current time zone is. The range of values is -12:00 to +13:00. If the offset is a single digit (0–9), it’s formatted with a preceding 0 (01–09) with an appropriate leading sign.
The value represented by this specifier cannot be edited.
| |
:
|
Time separator. The actual time separator is determined by the DateTimeFormatInfo.TimeSeparator property of the current culture.
| |
/
|
Date separator. The actual date separator is determined by the DateTimeFormatInfo.DateSeparator property of the current culture.
| |
“abc“ or ‘abc‘
|
Quoted string. Inserts the string enclosed with single or double quotes to the edit box. The string cannot be edited.
| |
%c
|
Where c is one of the standard mask specifiers, interprets the specifier as a custom mask specifier.
If a mask specifier is used alone as a single character, it’s interpreted as a standard mask specifier. Only mask specifiers consisting of two or more characters are interpreted as custom specifiers. In order to use a custom specifier which matches one of the standard specifiers, on its own, it should be preceded with the % character.
| |
_c_
|
The backslash is used as the escape character. It inserts the following character literally to the edit box.
| |
Any other characters.
|
The other characters are inserted to the edit box literally.
|
yyyy mask), an end user can enter the required year using the last two (or one) digits of this year. The century will be determined automatically based upon the current culture (see the TwoDigitYearMax topic). To insert a year that belongs to the first century, press the ‘0’ character before entering the year.The following are examples of custom date/time masks. See the Predefined Masks sub-section for examples of predefined masks.
The mask that requires the year to be entered at the first position, the month at the second and the day at the third position. The - characters are used as the date separators: yyyy-MM-dd
The same mask, but the months are edited using their abbreviated names. In addition, the name of the day is displayed to the right of the value: yyyy-MMM-dd dddd
The DateTimeMaskOptions.ChangeNextPartOnCycleValueChange property specifies whether a neighboring segment value should automatically increase or decrease when a user spins through values of one mask segment with editor buttons or arrow keys, and this value passes the minimum or maximum threshold.
An editor has the “HH:mm” (hours and minutes) mask and the current editor value is “00:59”. If a user spins the minute segment up, the editor value becomes “00:00” if the DateTimeMaskOptions.ChangeNextPartOnCycleValueChange property is disabled, or “01:00” when it is enabled. If a user decreases the minute segment value in an editor with a value of “01:00”, the resulting value is either “01:59” or “00:59” - based on the setting.
The following animation illustrates editor behavior with this property enabled:
The DateTimeKind attached property allows you to explicitly set the DateTime.Kind property (UTC, Local time, or neither) of a DateTime value (returned by the editor’s EditValue property).
<dxe:TextEdit MaskType="DateTime" Mask="d" dxe:DateTimeMaskOptions.DateTimeKind="Utc"/>
<dxe:DateEdit dxe:DateTimeMaskOptions.DateTimeKind="Local"/>